{
  "schemaVersion": 1,
  "updatedAt": "2026-10-26",
  "contracts": [
    {
      "harness": "codex",
      "variant": "current",
      "default": true,
      "version": "0.164.0",
      "stability": "source-observed",
      "sourceRevision": "6aaac694803004a63c6f393d153c96d22521a6b9",
      "container": "JSON Lines, one record per line, appended as the session runs. Files idle for 7 days are compressed to `.jsonl.zst` (one zstd frame) and decompressed again on resume. There is no file header; the first line is always `session_meta`.",
      "discriminator": "`type`, then `payload.type` inside `response_item`, `event_msg`, `retained_context` and `realtime_item`, then `payload.item.type` (and `payload.item.kind` for extension items) inside `event_msg` `item_completed`. Messages are further split by `payload.role`.",
      "layout": [
        {
          "path": "$CODEX_HOME (default ~/.codex)",
          "kind": "other",
          "description": "Root of all Codex local state; overridable with CODEX_HOME."
        },
        {
          "path": "~/.codex/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDThh-mm-ss-<thread-id>.jsonl",
          "kind": "transcript",
          "description": "The rollout: one JSONL file per thread. Directory date and filename timestamp are LOCAL time at creation; the file is created lazily when the first item is persisted."
        },
        {
          "path": "~/.codex/sessions/YYYY/MM/DD/rollout-YYYY-MM-DDThh-mm-ss-<thread-id>_<rollout-id>.jsonl",
          "kind": "transcript",
          "description": "Rollout written by thread/revert (or other rollout-id overrides): same thread id, new rollout id. The previous file is left intact; state_5.sqlite threads.rollout_path says which is current."
        },
        {
          "path": "~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl.zst",
          "kind": "transcript",
          "description": "Same rollout zstd-compressed (level 3) by a background worker once unmodified for 7 days; exactly one of .jsonl/.jsonl.zst exists. Decompressed back to .jsonl before any append (resume)."
        },
        {
          "path": "~/.codex/archived_sessions/rollout-...jsonl[.zst]",
          "kind": "transcript",
          "description": "Archived rollouts, moved flat (no date folders) with the same filename."
        },
        {
          "path": "~/.codex/session_index.jsonl",
          "kind": "index",
          "description": "Append-only thread names: {id, thread_name, updated_at(RFC3339)}; the last entry for an id wins."
        },
        {
          "path": "~/.codex/history.jsonl",
          "kind": "history",
          "description": "Prompt history across sessions (not a transcript): {session_id, ts (Unix seconds), text}."
        },
        {
          "path": "~/.codex/state_5.sqlite (+ -wal, -shm)",
          "kind": "database",
          "description": "Thread metadata index: threads (id, rollout_path, created_at[_ms], updated_at[_ms], source, model_provider, model, reasoning_effort, cwd, title, name, preview, first_user_message, tokens_used, archived, git_*, cli_version, agent_*, history_mode, thread_source, ...), thread_spawn_edges, thread_dynamic_tools, rollout_migration_state, etc. Authoritative for which rollout file is current."
        },
        {
          "path": "~/.codex/thread_history_1.sqlite (+ -wal, -shm)",
          "kind": "database",
          "description": "Projection of paginated rollouts for paging: thread_turns (turn_id, rollout_ordinal, status, timestamps, byte offsets), thread_items (item_json in app-server camelCase ThreadItem form, item_type e.g. userMessage, rollout_ordinal, updated_at_ordinal), thread_realtime_items, thread_history_projection_state (next byte offset/ordinal). Rebuildable from the rollout."
        },
        {
          "path": "~/.codex/logs_2.sqlite, goals_1.sqlite, memories_1.sqlite, queue_1.sqlite",
          "kind": "database",
          "description": "Logs, thread goals, memories, and queued input; not transcript content but keyed by thread id."
        },
        {
          "path": "~/.codex/rollout-migrations/<thread-id>.pending",
          "kind": "other",
          "description": "Journal for the in-place legacy -> paginated rollout migration (legacy_to_paginated_v1) that runs at startup."
        },
        {
          "path": "~/.codex/thread-writer-locks/<thread-id>.lock",
          "kind": "other",
          "description": "Per-thread writer lock files."
        },
        {
          "path": "~/.codex/shell_snapshots/<session-id>.<nonce>.sh",
          "kind": "sidecar",
          "description": "Captured login-shell environment snapshot used for command execution."
        },
        {
          "path": "~/.codex/generated_images/<thread-id>/<call-id>.png",
          "kind": "blob-store",
          "description": "Saved generated images referenced by saved_path/savedPath."
        }
      ],
      "envelope": [
        {
          "name": "timestamp",
          "type": "string",
          "required": true,
          "description": "Write time, UTC, format YYYY-MM-DDTHH:MM:SS.mmmZ (milliseconds)."
        },
        {
          "name": "ordinal",
          "type": "integer",
          "required": false,
          "description": "Present only in paginated rollouts: dense 0-based position in the logical thread history (session_meta of a root thread is 0; a fork/revert file starts at history_base.end_ordinal_exclusive). Absent in legacy rollouts."
        },
        {
          "name": "type",
          "type": "enum(session_meta|response_item|inter_agent_communication|inter_agent_communication_metadata|compacted|turn_context|token_usage_record|world_state|retained_context|security_risk_score|event_msg|realtime_item)",
          "required": true,
          "description": "Rollout item kind (snake_case)."
        },
        {
          "name": "payload",
          "type": "object",
          "required": true,
          "description": "Item body; for response_item, event_msg, retained_context and realtime_item it carries its own payload.type."
        },
        {
          "name": "metadata",
          "type": "object",
          "required": false,
          "description": "Only on response_item: CodexHarnessMetadata {client_authored (bool, always written), fallback_token_limit_override, retained_source{id{message_id,turn_id,role},revision,complete}, user_input_order, guardian_sources, guardian_review_ids, guardian_source_order_guidance, guardian_retained_omissions, delivered_assistant_message, harness_authored_configuration, compaction_model_hash, compaction_output, inherited_user_message, mcp_attribution, sender_user_messages}."
        }
      ],
      "records": [
        {
          "type": "session_meta",
          "concept": "session-header",
          "summary": "Identifies the thread and records how, where and by which build it was created.",
          "when": "First line of every rollout when the file is materialized (creation is deferred until the first item is persisted). Not rewritten on resume. Legacy forks may contain later session_meta lines copied from the parent; only the first belongs to this file.",
          "fields": [
            {
              "name": "id",
              "type": "string(uuid)",
              "required": true,
              "description": "Thread id (stable across revert)."
            },
            {
              "name": "session_id",
              "type": "string(uuid)",
              "required": true,
              "description": "Root thread id of the session tree. Backfilled from id when absent in older files."
            },
            {
              "name": "timestamp",
              "type": "string(RFC3339 UTC, ms)",
              "required": true,
              "description": "Thread creation time."
            },
            {
              "name": "cwd",
              "type": "string(path)",
              "required": true,
              "description": "Working directory at creation."
            },
            {
              "name": "originator",
              "type": "string",
              "required": true,
              "description": "Client originator (e.g. codex_cli_rs, codex_vscode)."
            },
            {
              "name": "cli_version",
              "type": "string",
              "required": true,
              "description": "Version of the build that created the thread; NOT updated by later writers or by legacy->paginated migration."
            },
            {
              "name": "source",
              "type": "string | object",
              "required": false,
              "description": "SessionSource, lowercase externally tagged: \"cli\" | \"vscode\" | \"exec\" | \"mcp\" | \"unknown\" | {\"custom\":string} | {\"internal\":\"memory_consolidation\"|\"guardian\"} | {\"subagent\": \"review\"|\"compact\"|\"memory_consolidation\"|{\"thread_spawn\":{parent_thread_id,depth,agent_path?,agent_nickname?,agent_role?}}|{\"other\":string}}. Defaults to vscode when absent."
            },
            {
              "name": "thread_source",
              "type": "string",
              "required": false,
              "description": "Analytics classification: user | subagent | guardian_review | memory_consolidation | <feature string>."
            },
            {
              "name": "forked_from_id",
              "type": "string(uuid)",
              "required": false,
              "description": "Thread this one was forked from."
            },
            {
              "name": "forked_from_ordinal_exclusive",
              "type": "integer",
              "required": false,
              "description": "Fork boundary in the parent's paginated history (only with forked_from_id)."
            },
            {
              "name": "parent_thread_id",
              "type": "string(uuid)",
              "required": false,
              "description": "Parent thread for spawned sub-agents."
            },
            {
              "name": "runtime_workspace_roots",
              "type": "string[]",
              "required": false,
              "description": "Workspace roots at creation; absent = unknown, [] = none."
            },
            {
              "name": "creator_user_id",
              "type": "string",
              "required": false,
              "description": "ChatGPT user that created the thread."
            },
            {
              "name": "creator_account_id",
              "type": "string",
              "required": false,
              "description": "ChatGPT account selected at creation."
            },
            {
              "name": "agent_nickname",
              "type": "string",
              "required": false,
              "description": "Nickname of a spawned sub-agent."
            },
            {
              "name": "agent_role",
              "type": "string",
              "required": false,
              "description": "Role of a spawned sub-agent. Alias on read: agent_type."
            },
            {
              "name": "agent_path",
              "type": "string",
              "required": false,
              "description": "Canonical agent path of a spawned sub-agent."
            },
            {
              "name": "model_provider",
              "type": "string | null",
              "required": true,
              "description": "Model provider id."
            },
            {
              "name": "base_instructions",
              "type": "object | null",
              "required": true,
              "description": "{text, provenance?} system instructions for the thread."
            },
            {
              "name": "dynamic_tools",
              "type": "array",
              "required": false,
              "description": "Client-supplied dynamic tool specs (older flat camelCase shape also accepted on read)."
            },
            {
              "name": "selected_capability_roots",
              "type": "array",
              "required": false,
              "description": "Capability roots selected by the hosting platform."
            },
            {
              "name": "memory_mode",
              "type": "string",
              "required": false,
              "description": "\"disabled\" when memory generation is off."
            },
            {
              "name": "history_mode",
              "type": "enum(legacy|paginated)",
              "required": false,
              "description": "Format discriminator for the whole file; absent = legacy. Unknown values make Codex reject the file."
            },
            {
              "name": "history_base",
              "type": "object",
              "required": false,
              "description": "{thread_id (actually a rollout id), end_ordinal_exclusive, end_byte_offset}: immutable prefix of another paginated rollout inherited by this one (forks and reverts)."
            },
            {
              "name": "subagent_history_start_ordinal",
              "type": "integer",
              "required": false,
              "description": "First ordinal that belongs to this sub-agent's own history; earlier records are inherited parent context."
            },
            {
              "name": "multi_agent_version",
              "type": "enum(disabled|v1|v2)",
              "required": false,
              "description": "Multi-agent protocol version."
            },
            {
              "name": "context_window",
              "type": "object",
              "required": false,
              "description": "{window_id}: initial context-window identity (UUIDv7)."
            },
            {
              "name": "git",
              "type": "object",
              "required": false,
              "description": "{commit_hash?, branch?, repository_url?} collected when cwd is inside a git repo; URL is sanitized."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":0,\"type\":\"session_meta\",\"payload\":{\"id\":\"0199aaaa-0000-7000-8000-000000000001\",\"session_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"timestamp\":\"2026-01-02T03:04:05.600Z\",\"cwd\":\"/home/user/project\",\"originator\":\"codex_cli_rs\",\"cli_version\":\"0.164.0\",\"source\":\"cli\",\"thread_source\":\"user\",\"model_provider\":\"openai\",\"base_instructions\":{\"text\":\"You are a coding agent.\"},\"history_mode\":\"paginated\",\"context_window\":{\"window_id\":\"0199aaaa-0000-7000-8000-0000000000ff\"},\"git\":{\"commit_hash\":\"0123456789abcdef0123456789abcdef01234567\",\"branch\":\"main\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3256-L3330",
          "notes": [
            "git is flattened into the same payload object (SessionMetaLine = SessionMeta + git).",
            "Source values include \"cli\", \"vscode\", \"exec\", and {\"subagent\":...} with review / thread_spawn / other.",
            "SessionSource is externally tagged lowercase, so a sub-agent appears as {\"subagent\":{\"thread_spawn\":{...}}}, not as a type field."
          ]
        },
        {
          "type": "turn_context",
          "concept": "session-settings",
          "summary": "Model, cwd, approval and sandbox settings that applied to one turn.",
          "when": "Once per real user turn after model-visible context updates are computed, and again after mid-turn compaction re-establishes context.",
          "fields": [
            {
              "name": "turn_id",
              "type": "string",
              "required": false,
              "description": "Turn this context belongs to."
            },
            {
              "name": "root_turn_id",
              "type": "string",
              "required": false,
              "description": "Causal root turn."
            },
            {
              "name": "cwd",
              "type": "string(path)",
              "required": true,
              "description": "Absolute working directory."
            },
            {
              "name": "approval_policy",
              "type": "string | object",
              "required": true,
              "description": "AskForApproval: \"untrusted\" | \"on-request\" (alias on-failure) | \"never\" | {\"granular\":{...}}."
            },
            {
              "name": "approvals_reviewer",
              "type": "enum(user|auto_review)",
              "required": false,
              "description": "Who reviews approvals (alias guardian_subagent)."
            },
            {
              "name": "sandbox_policy",
              "type": "object",
              "required": true,
              "description": "{type: danger-full-access | read-only | workspace-write | external-sandbox, writable_roots?, network_access?, exclude_tmpdir_env_var?, exclude_slash_tmp?}."
            },
            {
              "name": "permission_profile",
              "type": "object",
              "required": false,
              "description": "Resolved permission profile {type, file_system, network}."
            },
            {
              "name": "active_permission_profile",
              "type": "object",
              "required": false,
              "description": "Named/built-in profile that produced permission_profile."
            },
            {
              "name": "file_system_sandbox_policy",
              "type": "object",
              "required": false,
              "description": "Raw filesystem sandbox policy."
            },
            {
              "name": "model",
              "type": "string",
              "required": true,
              "description": "Model slug used for the turn."
            },
            {
              "name": "comp_hash",
              "type": "string",
              "required": false,
              "description": "Opaque compatibility hash."
            },
            {
              "name": "collaboration_mode",
              "type": "object",
              "required": false,
              "description": "{mode: plan|default, settings:{...}}."
            },
            {
              "name": "multi_agent_version",
              "type": "enum(disabled|v1|v2)",
              "required": false,
              "description": "—"
            },
            {
              "name": "realtime_active",
              "type": "boolean",
              "required": false,
              "description": "Realtime voice session active."
            },
            {
              "name": "cyber_access_program",
              "type": "object",
              "required": false,
              "description": "Cyber access program state."
            },
            {
              "name": "disabled_plugin_ids",
              "type": "string[]",
              "required": false,
              "description": "Plugin selection for the turn."
            },
            {
              "name": "effort",
              "type": "enum(none|minimal|low|medium|high|xhigh|max|ultra|persistent)",
              "required": false,
              "description": "Reasoning effort."
            },
            {
              "name": "summary",
              "type": "enum(auto|concise|detailed|none)",
              "required": false,
              "description": "Legacy reasoning-summary placeholder, now written as \"none\" for older readers."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"turn_context\",\"payload\":{\"turn_id\":\"0199aaaa-0000-7000-8000-000000000010\",\"cwd\":\"/home/user/project\",\"approval_policy\":\"on-request\",\"sandbox_policy\":{\"type\":\"workspace-write\",\"writable_roots\":[],\"network_access\":false,\"exclude_tmpdir_env_var\":false,\"exclude_slash_tmp\":false},\"model\":\"gpt-5-codex\",\"collaboration_mode\":{\"mode\":\"default\",\"settings\":{\"model\":\"gpt-5-codex\"}},\"effort\":\"medium\",\"summary\":\"none\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3424-L3470",
          "notes": [
            "Older files carry fields no longer in the struct and ignored on read: personality, current_date, timezone, workspace_roots (and, in early builds, user_instructions/developer_instructions)."
          ]
        },
        {
          "type": "token_usage_record",
          "concept": "token-usage",
          "summary": "Best-effort token usage for one completed Responses API response, with running turn and thread totals.",
          "when": "After each completed model response.",
          "fields": [
            {
              "name": "thread_id",
              "type": "string(uuid)",
              "required": true,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "string(uuid)",
              "required": true,
              "description": "Root session id."
            },
            {
              "name": "root_turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "response_id",
              "type": "string",
              "required": true,
              "description": "Responses API response id."
            },
            {
              "name": "usage",
              "type": "TokenUsage",
              "required": true,
              "description": "This response: {input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens, total_tokens}."
            },
            {
              "name": "turn_token_usage",
              "type": "TokenUsage",
              "required": true,
              "description": "Cumulative for the turn."
            },
            {
              "name": "thread_token_usage",
              "type": "TokenUsage",
              "required": true,
              "description": "Cumulative for the thread."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"token_usage_record\",\"payload\":{\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"0199aaaa-0000-7000-8000-000000000010\",\"session_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"root_turn_id\":\"0199aaaa-0000-7000-8000-000000000010\",\"response_id\":\"resp_123\",\"usage\":{\"input_tokens\":1200,\"cached_input_tokens\":1000,\"cache_write_input_tokens\":0,\"output_tokens\":80,\"reasoning_output_tokens\":40,\"total_tokens\":1280},\"turn_token_usage\":{\"input_tokens\":1200,\"cached_input_tokens\":1000,\"cache_write_input_tokens\":0,\"output_tokens\":80,\"reasoning_output_tokens\":40,\"total_tokens\":1280},\"thread_token_usage\":{\"input_tokens\":5000,\"cached_input_tokens\":3000,\"cache_write_input_tokens\":0,\"output_tokens\":400,\"reasoning_output_tokens\":200,\"total_tokens\":5400}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2368-L2402"
        },
        {
          "type": "compacted",
          "concept": "compaction",
          "summary": "A context compaction checkpoint; when replacement_history is present it is the complete new model history.",
          "when": "When the conversation is compacted (manual /compact or automatic).",
          "fields": [
            {
              "name": "message",
              "type": "string",
              "required": true,
              "description": "Summary text (may be empty for remote/encrypted compaction)."
            },
            {
              "name": "replacement_history",
              "type": "ResponseItem[]",
              "required": false,
              "description": "Complete history after compaction; same shapes as response_item payloads. Absent in early legacy rollouts."
            },
            {
              "name": "replacement_history_metadata",
              "type": "CodexHarnessMetadata[]",
              "required": false,
              "description": "Parallel array of per-item metadata; must have the same length as replacement_history."
            },
            {
              "name": "guardian_history",
              "type": "object",
              "required": false,
              "description": "Guardian reviewer history checkpoint."
            },
            {
              "name": "retained_context",
              "type": "object",
              "required": false,
              "description": "Snapshot of retained verified answers / user and assistant messages {verified_answers, incomplete, user_messages, user_messages_incomplete, assistant_messages, assistant_messages_incomplete, next_order, sender_deliveries?}."
            },
            {
              "name": "mcp_resource_origins",
              "type": "object",
              "required": false,
              "description": "MCP resource origin checkpoint."
            },
            {
              "name": "window_number",
              "type": "integer",
              "required": false,
              "description": "Context-window sequence number."
            },
            {
              "name": "first_window_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "previous_window_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "window_id",
              "type": "string | integer",
              "required": false,
              "description": "New window id; older rollouts stored the numeric window number here."
            },
            {
              "name": "compaction_response_id",
              "type": "string | null",
              "required": false,
              "description": "Responses API id for the compaction request; serialized as null when absent."
            },
            {
              "name": "latest_token_usage_record",
              "type": "TokenUsageRecord | null",
              "required": false,
              "description": "Latest usage snapshot at compaction time; serialized as null when absent."
            },
            {
              "name": "resume_metadata",
              "type": "object",
              "required": false,
              "description": "Values needed by resume that are not in companion records."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"compacted\",\"payload\":{\"message\":\"Summary of earlier work.\",\"replacement_history\":[{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Fix the failing test.\"}]},{\"type\":\"compaction\",\"encrypted_content\":\"gAAAA...\"}],\"window_number\":2,\"window_id\":\"0199aaaa-0000-7000-8000-000000000020\",\"previous_window_id\":\"0199aaaa-0000-7000-8000-0000000000ff\",\"first_window_id\":\"0199aaaa-0000-7000-8000-0000000000ff\",\"compaction_response_id\":null,\"latest_token_usage_record\":null}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/history/src/rollout_payload.rs#L249-L276",
          "notes": [
            "Legacy ghost_snapshot entries inside replacement_history are stripped on read."
          ]
        },
        {
          "type": "world_state",
          "concept": "workspace-state",
          "summary": "Persisted comparison state for model-visible world-state diffing (full snapshot or patch).",
          "when": "When world-state context is computed for a turn; full snapshots establish a new baseline.",
          "fields": [
            {
              "name": "full",
              "type": "boolean",
              "required": true,
              "description": "true = full baseline; false = patch onto the current baseline."
            },
            {
              "name": "state",
              "type": "object",
              "required": true,
              "description": "Opaque key/value map."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"world_state\",\"payload\":{\"full\":true,\"state\":{\"example_key\":\"example_value\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3405-L3420"
        },
        {
          "type": "inter_agent_communication",
          "concept": "user-message",
          "summary": "A message between agents in a multi-agent tree, recorded as history of the recipient.",
          "when": "When an agent sends a message or task to another agent through the thread submission lifecycle.",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "author",
              "type": "string",
              "required": true,
              "description": "Sender agent path."
            },
            {
              "name": "recipient",
              "type": "string",
              "required": true,
              "description": "Recipient agent path."
            },
            {
              "name": "other_recipients",
              "type": "string[]",
              "required": true,
              "description": "Defaults to []."
            },
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "Plain text (empty when encrypted_content is set)."
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            },
            {
              "name": "trigger_turn",
              "type": "boolean",
              "required": true,
              "description": "Whether delivery starts a turn (NEW_TASK vs MESSAGE)."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"inter_agent_communication\",\"payload\":{\"author\":\"/root\",\"recipient\":\"/root/worker\",\"other_recipients\":[],\"content\":\"Please check the tests.\",\"trigger_turn\":true}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L913-L930",
          "notes": [
            "Concept is user-message for the recipient: it is input from another agent, not from the human."
          ]
        },
        {
          "type": "inter_agent_communication_metadata",
          "concept": "queue",
          "summary": "Records whether a delivered inter-agent message triggered a turn.",
          "when": "Alongside inter-agent message delivery.",
          "fields": [
            {
              "name": "trigger_turn",
              "type": "boolean",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"inter_agent_communication_metadata\",\"payload\":{\"trigger_turn\":false}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/history/src/rollout_payload.rs#L31-L72"
        },
        {
          "type": "security_risk_score",
          "concept": "permission",
          "summary": "Security-risk classifier scores for a reviewed tool action; never model- or user-visible.",
          "when": "When a security risk classifier scores an action.",
          "fields": [
            {
              "name": "scores",
              "type": "object<string, number>",
              "required": true,
              "description": "Classifier name -> score."
            },
            {
              "name": "call_id",
              "type": "string",
              "required": false,
              "description": "Tool call that produced the score."
            },
            {
              "name": "action",
              "type": "any",
              "required": false,
              "description": "Bounded description of the reviewed action."
            },
            {
              "name": "sampled_at",
              "type": "string(RFC3339)",
              "required": false,
              "description": "When sampling started."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"security_risk_score\",\"payload\":{\"scores\":{\"example_classifier\":0.02},\"call_id\":\"call_abc\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/security_risk.rs#L9-L25"
        },
        {
          "type": "retained_context / verified_answer",
          "concept": "metadata-other",
          "summary": "Host-only record of user answers verified for a request_user_input-style call, retained for delegated review.",
          "when": "When a question/answer exchange is accepted.",
          "fields": [
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "questions",
              "type": "array",
              "required": true,
              "description": "[{question, answer}]"
            },
            {
              "name": "acceptance_order",
              "type": "integer",
              "required": false,
              "description": "Absent in legacy events."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"retained_context\",\"payload\":{\"type\":\"verified_answer\",\"turn_id\":\"t1\",\"call_id\":\"call_abc\",\"questions\":[{\"question\":\"Proceed?\",\"answer\":\"Yes\"}],\"acceptance_order\":3}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/history/src/retained_context.rs#L144-L161",
          "notes": [
            "The other RetainedContextEvent variant, delivered_assistant_message, is never written as retained_context: it is rewritten as a response_item assistant message with metadata.delivered_assistant_message = \"codex:code-mode-delivery:v1:complete\" (or \"...:incomplete:<text>\") and metadata.user_input_order, and turned back into the event on read. https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/history/src/rollout_payload.rs#L106-L149"
          ]
        },
        {
          "type": "realtime_item / realtime_session_started",
          "concept": "turn-start",
          "summary": "A realtime voice session began.",
          "when": "During realtime (voice) sessions; paginated threads only.",
          "persisted": "only history_mode = paginated only; dropped in legacy",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "realtime_session_id",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"realtime_item\",\"payload\":{\"id\":\"rt1\",\"realtime_session_id\":\"rs1\",\"type\":\"realtime_session_started\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/realtime.rs#L6-L59",
          "notes": [
            "RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id."
          ]
        },
        {
          "type": "realtime_item / transcript_segment",
          "concept": "user-message",
          "summary": "A transcribed realtime speech segment (role user or assistant).",
          "when": "During realtime (voice) sessions; paginated threads only.",
          "persisted": "only history_mode = paginated only; dropped in legacy",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "realtime_session_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "role",
              "type": "enum(user|assistant)",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"realtime_item\",\"payload\":{\"id\":\"rt1\",\"realtime_session_id\":\"rs1\",\"type\":\"transcript_segment\",\"role\":\"user\",\"text\":\"Hello\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/realtime.rs#L6-L59",
          "notes": [
            "RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id."
          ]
        },
        {
          "type": "realtime_item / bem_item_promoted",
          "concept": "metadata-other",
          "summary": "An existing agent item was presented inside the realtime conversation.",
          "when": "During realtime (voice) sessions; paginated threads only.",
          "persisted": "only history_mode = paginated only; dropped in legacy",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "realtime_session_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "presentation",
              "type": "object",
              "required": true,
              "description": "{type: whole_item | inline_markdown | inline_visualization, index?}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"realtime_item\",\"payload\":{\"id\":\"rt1\",\"realtime_session_id\":\"rs1\",\"type\":\"bem_item_promoted\",\"turn_id\":\"t1\",\"item_id\":\"i1\",\"presentation\":{\"type\":\"whole_item\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/realtime.rs#L6-L59",
          "notes": [
            "RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id."
          ]
        },
        {
          "type": "realtime_item / realtime_session_closed",
          "concept": "turn-end",
          "summary": "A realtime session ended.",
          "when": "During realtime (voice) sessions; paginated threads only.",
          "persisted": "only history_mode = paginated only; dropped in legacy",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "realtime_session_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "outcome",
              "type": "enum(ended|failed)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"realtime_item\",\"payload\":{\"id\":\"rt1\",\"realtime_session_id\":\"rs1\",\"type\":\"realtime_session_closed\",\"outcome\":\"ended\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/realtime.rs#L6-L59",
          "notes": [
            "RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id."
          ]
        },
        {
          "type": "response_item / message (role=user)",
          "concept": "user-message",
          "summary": "A user message as sent to the model (also used for injected user-role context such as AGENTS.md and environment context).",
          "when": "When user input is recorded for a turn; also for harness-injected user-role context fragments.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "role",
              "type": "string",
              "required": true,
              "description": "\"user\""
            },
            {
              "name": "content",
              "type": "ContentItem[]",
              "required": true,
              "description": "input_text / input_image / input_audio blocks."
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "phase",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"Fix the failing test.\"}]},\"metadata\":{\"client_authored\":false,\"user_input_order\":1}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1062-L1083",
          "notes": [
            "Injected context (AGENTS.md, environment_context, skills) is also role=user; distinguish via internal_chat_message_metadata_passthrough.content_item_metadata[].provenance when present, otherwise by text markers such as <environment_context> or # AGENTS.md.",
            "metadata (sibling of payload) carries CodexHarnessMetadata; see the envelope."
          ]
        },
        {
          "type": "response_item / message (role=assistant)",
          "concept": "assistant-message",
          "summary": "Assistant output text.",
          "when": "When the model emits an output message.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "role",
              "type": "string",
              "required": true,
              "description": "\"assistant\""
            },
            {
              "name": "content",
              "type": "ContentItem[]",
              "required": true,
              "description": "output_text blocks."
            },
            {
              "name": "phase",
              "type": "enum(commentary|partial_answer|final_answer)",
              "required": false,
              "description": "Absent = unknown (older models/providers)."
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"message\",\"role\":\"assistant\",\"id\":\"msg_123\",\"content\":[{\"type\":\"output_text\",\"text\":\"Done.\"}],\"phase\":\"final_answer\",\"internal_chat_message_metadata_passthrough\":{\"turn_id\":\"t1\",\"create_time\":1767323045.678}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1062-L1083",
          "notes": [
            "Also used for code-mode delivered assistant messages (see retained_context note)."
          ]
        },
        {
          "type": "response_item / message (role=developer)",
          "concept": "system-message",
          "summary": "Developer-role instructions/context injected by the harness (permissions, collaboration mode, skills, hook output, etc.).",
          "when": "At session start and whenever model-visible context changes.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "role",
              "type": "string",
              "required": true,
              "description": "\"developer\" (\"system\" is possible from older/other producers)"
            },
            {
              "name": "content",
              "type": "ContentItem[]",
              "required": true,
              "description": "input_text blocks."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"message\",\"role\":\"developer\",\"content\":[{\"type\":\"input_text\",\"text\":\"<permissions instructions>...</permissions instructions>\"}]},\"metadata\":{\"client_authored\":false}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1062-L1083",
          "notes": [
            "metadata.client_authored=true marks developer text supplied by the client rather than the harness."
          ]
        },
        {
          "type": "response_item / reasoning",
          "concept": "reasoning",
          "summary": "Model reasoning item: readable summaries plus (usually) encrypted reasoning content.",
          "when": "When the model emits reasoning.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "summary",
              "type": "array",
              "required": true,
              "description": "[{type:\"summary_text\", text}]"
            },
            {
              "name": "content",
              "type": "array",
              "required": false,
              "description": "[{type:\"reasoning_text\"|\"text\", text}] raw reasoning; omitted on write when absent or when it contains reasoning_text."
            },
            {
              "name": "encrypted_content",
              "type": "string | null",
              "required": true,
              "description": "Always serialized (null when absent)."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"reasoning\",\"id\":\"rs_123\",\"summary\":[{\"type\":\"summary_text\",\"text\":\"Inspecting the test.\"}],\"encrypted_content\":\"gAAAA...\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1095-L1107"
        },
        {
          "type": "response_item / function_call",
          "concept": "tool-call",
          "summary": "A JSON-arguments function tool call (shell, MCP tools, multi-agent tools, etc.).",
          "when": "When the model calls a function tool.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "Tool name."
            },
            {
              "name": "namespace",
              "type": "string",
              "required": false,
              "description": "Tool namespace (e.g. MCP server namespace)."
            },
            {
              "name": "arguments",
              "type": "string",
              "required": true,
              "description": "JSON-encoded arguments STRING, not an object."
            },
            {
              "name": "encrypted_function_args",
              "type": "string[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "Pairs with function_call_output.call_id."
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"function_call\",\"name\":\"exec_command\",\"arguments\":\"{\\\"cmd\\\":\\\"ls\\\"}\",\"call_id\":\"call_abc\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1124-L1149"
        },
        {
          "type": "response_item / function_call_output",
          "concept": "tool-result",
          "summary": "Result of a function tool call.",
          "when": "After the tool finishes.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string",
              "required": false,
              "description": "Matches function_call.call_id."
            },
            {
              "name": "name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "namespace",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "output",
              "type": "string | FunctionCallOutputContentItem[]",
              "required": true,
              "description": "Plain string, or an array of input_text / input_image / input_audio / encrypted_content items."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"function_call_output\",\"call_id\":\"call_abc\",\"output\":\"Process exited with code 0\\nOutput:\\nREADME.md\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1173-L1192",
          "notes": [
            "The success flag is internal and never serialized; success must be inferred from output text or from the paired item_completed event.",
            "Very early rollouts stored output as an object {content, success}; current deserializer accepts only string or array."
          ]
        },
        {
          "type": "response_item / custom_tool_call",
          "concept": "tool-call",
          "summary": "A freeform (grammar/plain-text input) tool call such as apply_patch or code-mode exec.",
          "when": "When the model calls a custom tool.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "namespace",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "input",
              "type": "string",
              "required": true,
              "description": "Raw freeform input (e.g. a patch)."
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"custom_tool_call\",\"status\":\"completed\",\"call_id\":\"call_def\",\"name\":\"apply_patch\",\"input\":\"*** Begin Patch\\n*** End Patch\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1193-L1213"
        },
        {
          "type": "response_item / custom_tool_call_output",
          "concept": "tool-result",
          "summary": "Result of a custom tool call.",
          "when": "After the custom tool finishes.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "output",
              "type": "string | FunctionCallOutputContentItem[]",
              "required": true,
              "description": "Same encoding as function_call_output.output."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"custom_tool_call_output\",\"call_id\":\"call_def\",\"output\":[{\"type\":\"input_text\",\"text\":\"Success. Updated the following files: M src/lib.rs\"}]}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1217-L1231"
        },
        {
          "type": "response_item / local_shell_call",
          "concept": "tool-call",
          "summary": "Responses API built-in local shell call (legacy shell tool).",
          "when": "When a model using the local_shell tool runs a command.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "status",
              "type": "enum(completed|in_progress|incomplete)",
              "required": true,
              "description": "—"
            },
            {
              "name": "action",
              "type": "object",
              "required": true,
              "description": "{type:\"exec\", command:string[], timeout_ms, working_directory, env, user}"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"local_shell_call\",\"call_id\":\"call_ls\",\"status\":\"completed\",\"action\":{\"type\":\"exec\",\"command\":[\"ls\"],\"timeout_ms\":null,\"working_directory\":null,\"env\":null,\"user\":null}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1108-L1123",
          "notes": ["Its result is recorded as function_call_output with the same call_id."]
        },
        {
          "type": "response_item / tool_search_call",
          "concept": "tool-call",
          "summary": "A tool-search request (deferred tool discovery).",
          "when": "When the model searches for tools.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "execution",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "arguments",
              "type": "any",
              "required": true,
              "description": "JSON value (not a string)."
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"tool_search_call\",\"call_id\":\"call_ts\",\"status\":\"completed\",\"execution\":\"client\",\"arguments\":{\"query\":\"calendar\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1150-L1167"
        },
        {
          "type": "response_item / tool_search_output",
          "concept": "tool-result",
          "summary": "Tools returned by a tool search.",
          "when": "After tool search completes.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "call_id",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "status",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "execution",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "tools",
              "type": "any[]",
              "required": true,
              "description": "Tool declarations."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"tool_search_output\",\"call_id\":\"call_ts\",\"status\":\"completed\",\"execution\":\"client\",\"tools\":[]}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1232-L1244"
        },
        {
          "type": "response_item / web_search_call",
          "concept": "tool-call",
          "summary": "Hosted web search performed by the Responses API (call and result in one item).",
          "when": "When the model uses hosted web search.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "status",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "action",
              "type": "object",
              "required": false,
              "description": "{type: search {query?, queries?} | open_page {url?} | find_in_page {url?, pattern?} | other}"
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"web_search_call\",\"status\":\"completed\",\"action\":{\"type\":\"search\",\"query\":\"rust serde flatten\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1253-L1270",
          "notes": [
            "Results are not in this item; paginated rollouts may carry them in item_completed WebSearch.results."
          ]
        },
        {
          "type": "response_item / image_generation_call",
          "concept": "tool-call",
          "summary": "Hosted image generation call including the base64 result.",
          "when": "When the model generates an image via the hosted tool.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "status",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "revised_prompt",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "result",
              "type": "string",
              "required": true,
              "description": "Base64 image data (can be very large)."
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"image_generation_call\",\"id\":\"ig_123\",\"status\":\"completed\",\"revised_prompt\":\"A blue square\",\"result\":\"iVBORw0KGgo=\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1279-L1294"
        },
        {
          "type": "response_item / agent_message",
          "concept": "user-message",
          "summary": "Model-visible inter-agent message (author -> recipient).",
          "when": "When a multi-agent v2 message is delivered into this agent's history.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "author",
              "type": "string",
              "required": true,
              "description": "Agent path."
            },
            {
              "name": "recipient",
              "type": "string",
              "required": true,
              "description": "Agent path."
            },
            {
              "name": "content",
              "type": "array",
              "required": true,
              "description": "[{type:\"input_text\", text} | {type:\"encrypted_content\", encrypted_content}]"
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"agent_message\",\"author\":\"/root\",\"recipient\":\"/root/worker\",\"content\":[{\"type\":\"input_text\",\"text\":\"Run the linter.\"}]}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1084-L1094"
        },
        {
          "type": "response_item / additional_tools",
          "concept": "session-settings",
          "summary": "Tool declarations added to the model's tool set at this point in history.",
          "when": "When tools are added mid-thread (e.g. after tool search or plugin enablement).",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "role",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "tools",
              "type": "any[]",
              "required": true,
              "description": "Tool declarations (JSON)."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"additional_tools\",\"role\":\"developer\",\"tools\":[{\"type\":\"function\",\"name\":\"example_tool\"}]}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1053-L1061"
        },
        {
          "type": "response_item / configuration_update",
          "concept": "session-settings",
          "summary": "Durable input control (reasoning effort) interpreted by the backend at this point in history.",
          "when": "When reasoning settings change mid-thread.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "reasoning",
              "type": "object",
              "required": true,
              "description": "{effort}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"configuration_update\",\"reasoning\":{\"effort\":\"high\"}},\"metadata\":{\"client_authored\":false,\"harness_authored_configuration\":true}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1306-L1310"
        },
        {
          "type": "response_item / compaction",
          "concept": "compaction",
          "summary": "Opaque encrypted compaction item returned by remote compaction; replaces summarized history for the model.",
          "when": "On remote/model-backed compaction.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"compaction\",\"id\":\"cmp_123\",\"encrypted_content\":\"gAAAA...\"},\"metadata\":{\"client_authored\":false,\"compaction_model_hash\":\"abc\",\"compaction_output\":true}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1295-L1305",
          "notes": ["Read alias: compaction_summary."]
        },
        {
          "type": "response_item / context_compaction",
          "concept": "compaction",
          "summary": "Context-compaction item from the Responses API (optionally encrypted).",
          "when": "On server-side context compaction.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "id",
              "type": "string",
              "required": false,
              "description": "Responses API item id (e.g. msg_..., rs_..., fc_...) or a harness-generated <prefix>_<uuidv7>."
            },
            {
              "name": "encrypted_content",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted payload."
            },
            {
              "name": "internal_chat_message_metadata_passthrough",
              "type": "object",
              "required": false,
              "description": "Harness metadata copied from the Responses API: turn_id (string), create_time (fractional Unix seconds), content_item_kinds (string[] aligned with content), content_item_metadata ([{provenance:{type: unknown|developer_instructions|skills|agents_md|harness|tool|user, ...}}] aligned with content). cell_id, executed_tool_calls and tool_calls_complete may be written but are ignored on read."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"response_item\",\"payload\":{\"type\":\"context_compaction\",\"id\":\"cc_123\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L1311-L1323"
        },
        {
          "type": "event_msg / task_started",
          "concept": "turn-start",
          "summary": "A turn began.",
          "when": "At the start of every turn (regular, review, compact, user shell).",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "root_turn_id",
              "type": "string",
              "required": false,
              "description": "Originating turn in the root thread."
            },
            {
              "name": "turn_attribution",
              "type": "object",
              "required": false,
              "description": "Provenance of a regular turn."
            },
            {
              "name": "trace_id",
              "type": "string",
              "required": false,
              "description": "Telemetry trace id."
            },
            {
              "name": "started_at",
              "type": "integer(Unix seconds)",
              "required": false,
              "description": "—"
            },
            {
              "name": "model_context_window",
              "type": "integer | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "collaboration_mode_kind",
              "type": "enum(plan|default)",
              "required": false,
              "description": "Aliases on read: code, pair_programming, execute, custom."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"task_started\",\"turn_id\":\"t1\",\"started_at\":1767323045,\"model_context_window\":258400,\"collaboration_mode_kind\":\"default\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L1519-L1520",
          "notes": [
            "Serialized name is task_started; turn_started is accepted as an alias on read."
          ]
        },
        {
          "type": "event_msg / task_complete",
          "concept": "turn-end",
          "summary": "A turn finished (successfully or with a terminal error).",
          "when": "At the end of a turn.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "root_turn_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "last_agent_message",
              "type": "string | null",
              "required": true,
              "description": "Final assistant text."
            },
            {
              "name": "error",
              "type": "object",
              "required": false,
              "description": "{message, codex_error_info?} when the turn failed."
            },
            {
              "name": "started_at",
              "type": "integer",
              "required": false,
              "description": "Unix seconds"
            },
            {
              "name": "completed_at",
              "type": "integer",
              "required": false,
              "description": "Unix seconds"
            },
            {
              "name": "duration_ms",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "time_to_first_token_ms",
              "type": "integer",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"task_complete\",\"turn_id\":\"t1\",\"last_agent_message\":\"Done.\",\"started_at\":1767323045,\"completed_at\":1767323100,\"duration_ms\":55000,\"time_to_first_token_ms\":900}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L1528-L1529",
          "notes": [
            "Serialized name task_complete; alias turn_complete on read.",
            "error.codex_error_info is an enum; misalignment details are never persisted."
          ]
        },
        {
          "type": "event_msg / turn_aborted",
          "concept": "turn-abort",
          "summary": "A turn was interrupted, replaced, ended by review, or budget-limited.",
          "when": "When a turn is aborted.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "turn_id",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "root_turn_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "reason",
              "type": "enum(interrupted|replaced|review_ended|budget_limited)",
              "required": true,
              "description": "—"
            },
            {
              "name": "error",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "started_at",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "completed_at",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "duration_ms",
              "type": "integer",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"turn_aborted\",\"turn_id\":\"t1\",\"reason\":\"interrupted\",\"completed_at\":1767323060,\"duration_ms\":15000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L4366-L4400"
        },
        {
          "type": "event_msg / token_count",
          "concept": "token-usage",
          "summary": "Cumulative and last-response token usage plus rate-limit snapshot.",
          "when": "After each model response and on rate-limit updates.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "info",
              "type": "object | null",
              "required": true,
              "description": "{total_token_usage: TokenUsage, last_token_usage: TokenUsage, model_context_window: integer|null}"
            },
            {
              "name": "rate_limits",
              "type": "object | null",
              "required": true,
              "description": "{limit_id, limit_name, normal_model_slug?, primary:{used_percent, window_minutes, resets_at}|null, secondary, credits:{has_credits, unlimited, balance}|null, individual_limit, spend_control_reached, plan_type, rate_limit_reached_type}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"token_count\",\"info\":{\"total_token_usage\":{\"input_tokens\":5000,\"cached_input_tokens\":3000,\"cache_write_input_tokens\":0,\"output_tokens\":400,\"reasoning_output_tokens\":200,\"total_tokens\":5400},\"last_token_usage\":{\"input_tokens\":1200,\"cached_input_tokens\":1000,\"cache_write_input_tokens\":0,\"output_tokens\":80,\"reasoning_output_tokens\":40,\"total_tokens\":1280},\"model_context_window\":258400},\"rate_limits\":{\"limit_id\":\"codex\",\"limit_name\":null,\"primary\":{\"used_percent\":12.0,\"window_minutes\":300,\"resets_at\":1767330000},\"secondary\":null,\"credits\":null,\"individual_limit\":null,\"spend_control_reached\":null,\"plan_type\":\"plus\",\"rate_limit_reached_type\":null}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2471-L2531",
          "notes": [
            "info may be null (rate-limit-only update). Do not sum token_count events: totals are already cumulative and some events repeat the same totals."
          ]
        },
        {
          "type": "event_msg / thread_settings_applied",
          "concept": "session-settings",
          "summary": "Snapshot of thread-level settings after they were applied.",
          "when": "When thread settings are applied or changed.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "thread_id",
              "type": "string(uuid)",
              "required": false,
              "description": "Owner thread; absent in older histories."
            },
            {
              "name": "thread_settings",
              "type": "object",
              "required": true,
              "description": "{model, model_provider_id, service_tier?, approval_policy, approvals_reviewer, permission_profile, active_permission_profile?, cwd, runtime_workspace_roots?, reasoning_effort?, reasoning_summary?, personality?, collaboration_mode, disabled_plugin_ids}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"thread_settings_applied\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"thread_settings\":{\"model\":\"gpt-5-codex\",\"model_provider_id\":\"openai\",\"approval_policy\":\"on-request\",\"approvals_reviewer\":\"user\",\"permission_profile\":{\"type\":\"managed\"},\"cwd\":\"/home/user/project\",\"collaboration_mode\":{\"mode\":\"default\",\"settings\":{\"model\":\"gpt-5-codex\"}},\"disabled_plugin_ids\":[]}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2328-L2366"
        },
        {
          "type": "event_msg / thread_goal_updated",
          "concept": "metadata-other",
          "summary": "The thread's goal (objective, status, budget) changed.",
          "when": "When a goal is created or updated.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "threadId",
              "type": "string(uuid)",
              "required": true,
              "description": "camelCase field names in this record."
            },
            {
              "name": "turnId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "goal",
              "type": "object",
              "required": true,
              "description": "{threadId, objective, status: active|paused|blocked|usageLimited|budgetLimited|complete, tokenBudget?, tokensUsed, timeUsedSeconds, createdAt, updatedAt}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"thread_goal_updated\",\"threadId\":\"0199aaaa-0000-7000-8000-000000000001\",\"goal\":{\"threadId\":\"0199aaaa-0000-7000-8000-000000000001\",\"objective\":\"Ship the fix\",\"status\":\"active\",\"tokensUsed\":0,\"timeUsedSeconds\":0,\"createdAt\":1767323045,\"updatedAt\":1767323045}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L4207-L4258"
        },
        {
          "type": "event_msg / thread_rolled_back",
          "concept": "summary",
          "summary": "The last N user turns were removed from model context (rewind).",
          "when": "When the user rolls back turns.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "num_turns",
              "type": "integer",
              "required": true,
              "description": "Number of user turns dropped."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"thread_rolled_back\",\"num_turns\":1}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3815-L3818",
          "notes": ["Concept is branches/rewind; see linking. Earlier records stay in the file."]
        },
        {
          "type": "event_msg / item_completed",
          "concept": "metadata-other",
          "summary": "Wrapper for a completed TurnItem (the paginated-mode canonical item stream).",
          "when": "When any turn item completes. Legacy mode keeps only items with no other lossless representation.",
          "persisted": "only paginated: every TurnItem, with CommandExecution.aggregated_output and McpToolCall.result truncated to 64 KiB; legacy: only FunctionCallOutput, Plan, Extension clock.sleep, and SubAgentActivity kind=completed",
          "fields": [
            {
              "name": "thread_id",
              "type": "string(uuid)",
              "required": true,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item",
              "type": "TurnItem",
              "required": true,
              "description": "Tagged by item.type (PascalCase variant names); see item_completed sub-records."
            },
            {
              "name": "started_at_ms",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "completed_at_ms",
              "type": "integer",
              "required": true,
              "description": "Defaults to 0 for old records."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Plan\",\"id\":\"p1\",\"text\":\"1. Fix\"},\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2063-L2076"
        },
        {
          "type": "event_msg / user_message",
          "concept": "user-message",
          "summary": "UI-level user message (legacy history).",
          "when": "When the user submits input (legacy mode).",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "message",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "client_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "images",
              "type": "string[]",
              "required": false,
              "description": "Image URLs/data URLs."
            },
            {
              "name": "image_details",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "file_ids",
              "type": "string[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "file_id_details",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "image_order",
              "type": "enum(inline|file)[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "local_images",
              "type": "string[]",
              "required": true,
              "description": "Local image paths (default [])."
            },
            {
              "name": "local_image_details",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "audio",
              "type": "string[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "local_audio",
              "type": "string[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "text_elements",
              "type": "array",
              "required": true,
              "description": "[{byte_range:{start,end}, placeholder}]"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"user_message\",\"message\":\"Fix the failing test.\",\"local_images\":[],\"local_audio\":[],\"text_elements\":[]}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2670-L2722",
          "notes": [
            "Contains the user's text without injected context, unlike response_item/message role=user."
          ]
        },
        {
          "type": "event_msg / agent_message",
          "concept": "assistant-message",
          "summary": "UI-level assistant message (legacy history).",
          "when": "When the assistant produces a message (legacy mode).",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "message",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "phase",
              "type": "string | null",
              "required": false,
              "description": "—"
            },
            {
              "name": "memory_citation",
              "type": "object | null",
              "required": false,
              "description": "—"
            },
            {
              "name": "delivery",
              "type": "enum(async)",
              "required": false,
              "description": "—"
            },
            {
              "name": "questions",
              "type": "array",
              "required": false,
              "description": "[{title, options}]"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"agent_message\",\"message\":\"Done.\",\"phase\":\"final_answer\",\"memory_citation\":null}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2647-L2660"
        },
        {
          "type": "event_msg / agent_reasoning",
          "concept": "reasoning",
          "summary": "UI-level reasoning summary text (legacy).",
          "when": "When a reasoning summary is produced (legacy).",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"agent_reasoning\",\"text\":\"**Inspecting** the test.\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2766-L2769"
        },
        {
          "type": "event_msg / agent_reasoning_raw_content",
          "concept": "reasoning",
          "summary": "UI-level raw reasoning text (legacy).",
          "when": "When raw reasoning is exposed (legacy).",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"agent_reasoning_raw_content\",\"text\":\"...\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2771-L2774"
        },
        {
          "type": "event_msg / entered_review_mode",
          "concept": "turn-start",
          "summary": "A /review sub-turn started (legacy).",
          "when": "When review mode starts.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "target",
              "type": "object",
              "required": true,
              "description": "{type: uncommittedChanges | baseBranch{branch} | commit{sha,title} | custom{instructions}}"
            },
            {
              "name": "user_facing_hint",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item_id",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"entered_review_mode\",\"target\":{\"type\":\"uncommittedChanges\"},\"user_facing_hint\":\"current changes\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2120-L2132"
        },
        {
          "type": "event_msg / exited_review_mode",
          "concept": "summary",
          "summary": "A review finished, with structured findings (legacy).",
          "when": "When review mode ends.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "turn_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "review_output",
              "type": "object | null",
              "required": true,
              "description": "{findings:[{title, body, confidence_score, priority, code_location:{absolute_file_path, line_range:{start,end}}}], overall_correctness, overall_explanation, overall_confidence_score}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"exited_review_mode\",\"review_output\":{\"findings\":[],\"overall_correctness\":\"patch is correct\",\"overall_explanation\":\"No issues.\",\"overall_confidence_score\":0.8}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2134-L2142"
        },
        {
          "type": "event_msg / patch_apply_end",
          "concept": "tool-result",
          "summary": "Outcome of applying a patch (legacy).",
          "when": "After apply_patch completes.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "Default \"\"."
            },
            {
              "name": "stdout",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "stderr",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "success",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "changes",
              "type": "object<path, FileChange>",
              "required": true,
              "description": "FileChange = {type:add,content} | {type:delete,content} | {type:update,unified_diff,move_path}"
            },
            {
              "name": "status",
              "type": "enum(completed|failed|declined)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"patch_apply_end\",\"call_id\":\"call_def\",\"turn_id\":\"t1\",\"stdout\":\"Success.\",\"stderr\":\"\",\"success\":true,\"changes\":{\"/home/user/project/a.txt\":{\"type\":\"add\",\"content\":\"hi\\n\"}},\"status\":\"completed\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3860-L3885"
        },
        {
          "type": "event_msg / context_compacted",
          "concept": "compaction",
          "summary": "Marker that context was compacted (legacy).",
          "when": "After compaction.",
          "persisted": "only history_mode = legacy only",
          "fields": [],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"context_compacted\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2269-L2270"
        },
        {
          "type": "event_msg / mcp_tool_call_end",
          "concept": "tool-result",
          "summary": "Completed MCP tool call with invocation and result (legacy).",
          "when": "After an MCP tool call.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "turn_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "invocation",
              "type": "object",
              "required": true,
              "description": "{server, tool, arguments}"
            },
            {
              "name": "connector_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "mcp_app_resource_uri",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "mcp_app_ui",
              "type": "object",
              "required": false,
              "description": "{resourceUri, preferredModelDisplayMode}"
            },
            {
              "name": "link_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "app_name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "action_name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "plugin_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "read_only_hint",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "duration",
              "type": "object",
              "required": true,
              "description": "Rust Duration {secs, nanos}."
            },
            {
              "name": "result",
              "type": "object",
              "required": true,
              "description": "Rust Result: {\"Ok\": CallToolResult{content, structuredContent?, isError?, _meta?}} or {\"Err\": string}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"mcp_tool_call_end\",\"call_id\":\"call_m\",\"turn_id\":\"t1\",\"invocation\":{\"server\":\"docs\",\"tool\":\"search\",\"arguments\":{\"q\":\"x\"}},\"duration\":{\"secs\":1,\"nanos\":5000000},\"result\":{\"Ok\":{\"content\":[{\"type\":\"text\",\"text\":\"result\"}]}}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2830-L2870"
        },
        {
          "type": "event_msg / web_search_end",
          "concept": "tool-result",
          "summary": "Completed web search with query and action (legacy).",
          "when": "After a web search.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "query",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "action",
              "type": "object",
              "required": true,
              "description": "Responses WebSearchAction (snake_case type)."
            },
            {
              "name": "results",
              "type": "any[]",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"web_search_end\",\"call_id\":\"ws_1\",\"query\":\"rust serde\",\"action\":{\"type\":\"search\",\"query\":\"rust serde\"}}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2908-L2917"
        },
        {
          "type": "event_msg / image_generation_end",
          "concept": "tool-result",
          "summary": "Completed image generation (legacy).",
          "when": "After image generation.",
          "persisted": "only history_mode = legacy only",
          "fields": [
            {
              "name": "call_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "status",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "revised_prompt",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "result | fileId",
              "type": "string",
              "required": true,
              "description": "Flattened GeneratedImageRef: either result (inline base64) or fileId."
            },
            {
              "name": "transparent_background",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "failure",
              "type": "object",
              "required": false,
              "description": "{type:usageLimitExceeded, limitId, resetsAt}"
            },
            {
              "name": "saved_path",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "input_images",
              "type": "array",
              "required": false,
              "description": "[{path, sha256}]"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"image_generation_end\",\"call_id\":\"ig_1\",\"status\":\"completed\",\"result\":\"iVBORw0KGgo=\",\"saved_path\":\"/home/user/.codex/generated_images/thread/ig_1.png\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L2924-L2945"
        },
        {
          "type": "event_msg / sub_agent_activity",
          "concept": "session-lineage",
          "summary": "A sub-agent was started, interacted with, or interrupted (legacy).",
          "when": "On sub-agent lifecycle activity (kind=completed is stored as an item_completed SubAgentActivity instead).",
          "persisted": "only history_mode = legacy and kind != completed",
          "fields": [
            {
              "name": "model",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "reasoning_effort",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "event_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "occurred_at_ms",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "agent_thread_id",
              "type": "string(uuid)",
              "required": true,
              "description": "Child thread id."
            },
            {
              "name": "agent_path",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "kind",
              "type": "enum(started|interacted|interrupted)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"type\":\"event_msg\",\"payload\":{\"type\":\"sub_agent_activity\",\"model\":null,\"reasoning_effort\":null,\"event_id\":\"e1\",\"occurred_at_ms\":1767323050000,\"agent_thread_id\":\"0199aaaa-0000-7000-8000-000000000002\",\"agent_path\":\"/root/worker\",\"kind\":\"started\"}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L4517-L4530"
        },
        {
          "type": "event_msg / item_completed / UserMessage",
          "concept": "user-message",
          "summary": "User input for the turn as the user entered it (no injected context).",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"UserMessage\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.client_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.content",
              "type": "UserInput[]",
              "required": true,
              "description": "text | image | local_image | audio | local_audio | skill | mention blocks (snake_case type)."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"UserMessage\",\"id\":\"u1\",\"content\":[{\"type\":\"text\",\"text\":\"Fix the failing test.\",\"text_elements\":[]}]},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L83-L89"
        },
        {
          "type": "event_msg / item_completed / AgentMessage",
          "concept": "assistant-message",
          "summary": "Assistant message as displayed.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"AgentMessage\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.content",
              "type": "array",
              "required": true,
              "description": "[{type:\"Text\", text}] (PascalCase type)."
            },
            {
              "name": "item.phase",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.memory_citation",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.delivery",
              "type": "enum(async)",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.questions",
              "type": "array",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"AgentMessage\",\"id\":\"msg_1\",\"content\":[{\"type\":\"Text\",\"text\":\"Done.\"}],\"phase\":\"final_answer\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L158-L177"
        },
        {
          "type": "event_msg / item_completed / Reasoning",
          "concept": "reasoning",
          "summary": "Reasoning summary and raw text as displayed.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"Reasoning\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.summary_text",
              "type": "string[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.raw_content",
              "type": "string[]",
              "required": true,
              "description": "Default []."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Reasoning\",\"id\":\"rs_1\",\"summary_text\":[\"Inspecting the test.\"],\"raw_content\":[]},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L199-L204"
        },
        {
          "type": "event_msg / item_completed / Plan",
          "concept": "metadata-other",
          "summary": "Plan text produced in plan collaboration mode.",
          "when": "When the item completes within a turn.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"Plan\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Plan\",\"id\":\"p1\",\"text\":\"1. Reproduce\\n2. Fix\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L193-L196"
        },
        {
          "type": "event_msg / item_completed / CommandExecution",
          "concept": "tool-result",
          "summary": "A shell command run, with output and exit code.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"CommandExecution\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "Tool call id."
            },
            {
              "name": "item.command",
              "type": "string[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.cwd",
              "type": "string(file URI)",
              "required": true,
              "description": "PathUri serialized as a URI string."
            },
            {
              "name": "item.parsed_cmd",
              "type": "array",
              "required": true,
              "description": "[{type: read{cmd,name,path} | list_files{cmd,path} | search{cmd,query,path} | unknown{cmd}}]"
            },
            {
              "name": "item.source",
              "type": "enum(agent|user_shell|unified_exec_startup|unified_exec_interaction)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "enum(in_progress|completed|failed|declined)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.aggregated_output",
              "type": "string",
              "required": false,
              "description": "Truncated in the middle to 64 KiB with marker \"... command output truncated for persistence ...\"."
            },
            {
              "name": "item.exit_code",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.duration",
              "type": "object",
              "required": false,
              "description": "{secs, nanos}"
            },
            {
              "name": "item.process_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.interaction_input",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.plugin_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.script_path",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"CommandExecution\",\"id\":\"call_abc\",\"command\":[\"/bin/zsh\",\"-lc\",\"ls\"],\"cwd\":\"file:///home/user/project\",\"parsed_cmd\":[{\"type\":\"list_files\",\"cmd\":\"ls\",\"path\":null}],\"source\":\"agent\",\"status\":\"completed\",\"aggregated_output\":\"README.md\\n\",\"exit_code\":0,\"duration\":{\"secs\":0,\"nanos\":120000000}},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L251-L287",
          "notes": [
            "Older files also carry stdout, stderr and formatted_output, which current builds ignore."
          ]
        },
        {
          "type": "event_msg / item_completed / FileChange",
          "concept": "tool-result",
          "summary": "Patch application result with per-file changes.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"FileChange\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.changes",
              "type": "object<path, FileChange>",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "enum(completed|failed|declined)",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.auto_approved",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.stdout",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.stderr",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"FileChange\",\"id\":\"call_def\",\"changes\":{\"/home/user/project/a.txt\":{\"type\":\"update\",\"unified_diff\":\"@@ -1 +1 @@\\n-a\\n+b\\n\",\"move_path\":null}},\"status\":\"completed\",\"stdout\":\"Success.\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L418-L432"
        },
        {
          "type": "event_msg / item_completed / McpToolCall",
          "concept": "tool-result",
          "summary": "MCP tool invocation with result (camelCase fields).",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"McpToolCall\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.server",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.tool",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.arguments",
              "type": "any",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.connectorId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.mcpAppResourceUri",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.mcpAppUi",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.linkId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.appName",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.actionName",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.pluginId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.readOnlyHint",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "enum(inProgress|completed|failed)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.result",
              "type": "object",
              "required": false,
              "description": "CallToolResult {content, structuredContent?, isError?, _meta?}, truncated to 64 KiB."
            },
            {
              "name": "item.error",
              "type": "object",
              "required": false,
              "description": "{message}"
            },
            {
              "name": "item.duration",
              "type": "object",
              "required": false,
              "description": "{secs, nanos}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"McpToolCall\",\"id\":\"call_m\",\"server\":\"docs\",\"tool\":\"search\",\"arguments\":{\"q\":\"x\"},\"status\":\"completed\",\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"result\"}]},\"duration\":{\"secs\":1,\"nanos\":0}},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L457-L514"
        },
        {
          "type": "event_msg / item_completed / DynamicToolCall",
          "concept": "tool-result",
          "summary": "Client-implemented dynamic tool call with result.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"DynamicToolCall\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.namespace",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.tool",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.arguments",
              "type": "any",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "enum(in_progress|completed|failed)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.content_items",
              "type": "array",
              "required": false,
              "description": "[{type: inputText|inputImage|inputAudio, ...}] (camelCase)"
            },
            {
              "name": "item.success",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.error",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.duration",
              "type": "object",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"DynamicToolCall\",\"id\":\"call_d\",\"tool\":\"lookup\",\"arguments\":{},\"status\":\"completed\",\"content_items\":[{\"type\":\"inputText\",\"text\":\"ok\"}],\"success\":true},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L299-L318"
        },
        {
          "type": "event_msg / item_completed / FunctionCallOutput",
          "concept": "tool-result",
          "summary": "Function tool output as a display item.",
          "when": "When the item completes within a turn.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"FunctionCallOutput\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.namespace",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.output",
              "type": "string | array",
              "required": true,
              "description": "FunctionCallOutputBody."
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"FunctionCallOutput\",\"id\":\"call_abc\",\"name\":\"example\",\"output\":\"ok\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L92-L98"
        },
        {
          "type": "event_msg / item_completed / CollabAgentToolCall",
          "concept": "session-lineage",
          "summary": "A multi-agent tool call (spawn, send, wait, close...) with target agents and states.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"CollabAgentToolCall\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.tool",
              "type": "enum(spawn_agent|send_input|resume_agent|wait|close_agent|send_message|followup_task|interrupt_agent|list_agents)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "enum(in_progress|completed|failed|interrupted)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.sender_thread_id",
              "type": "string(uuid)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.receiver_thread_ids",
              "type": "string[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.receiver_agents",
              "type": "array",
              "required": true,
              "description": "[{thread_id, agent_nickname?, agent_role?}]"
            },
            {
              "name": "item.prompt",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.model",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.reasoning_effort",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.agents_states",
              "type": "object<thread_id, AgentStatus>",
              "required": true,
              "description": "AgentStatus: \"pending_init\"|\"running\"|\"interrupted\"|\"shutdown\"|\"not_found\"|{\"completed\":string|null}|{\"errored\":string}"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"CollabAgentToolCall\",\"id\":\"call_c\",\"tool\":\"spawn_agent\",\"status\":\"completed\",\"sender_thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"receiver_thread_ids\":[\"0199aaaa-0000-7000-8000-000000000002\"],\"receiver_agents\":[],\"agents_states\":{}},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L322-L365"
        },
        {
          "type": "event_msg / item_completed / SubAgentActivity",
          "concept": "session-lineage",
          "summary": "Sub-agent lifecycle activity.",
          "when": "When the item completes within a turn.",
          "persisted": "only paginated: all kinds; legacy: kind=completed only",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"SubAgentActivity\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.kind",
              "type": "enum(started|interacted|interrupted|completed)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.agent_thread_id",
              "type": "string(uuid)",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.agent_path",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.model",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.reasoning_effort",
              "type": "string | null",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"SubAgentActivity\",\"id\":\"a1\",\"kind\":\"completed\",\"agent_thread_id\":\"0199aaaa-0000-7000-8000-000000000002\",\"agent_path\":\"/root/worker\",\"model\":null,\"reasoning_effort\":null},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L368-L377"
        },
        {
          "type": "event_msg / item_completed / WebSearch",
          "concept": "tool-result",
          "summary": "Hosted web search display item.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"WebSearch\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.query",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.action",
              "type": "object",
              "required": true,
              "description": "snake_case WebSearchAction"
            },
            {
              "name": "item.results",
              "type": "any[]",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"WebSearch\",\"id\":\"ws_1\",\"query\":\"rust serde\",\"action\":{\"type\":\"search\",\"query\":\"rust serde\"}},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L380-L391"
        },
        {
          "type": "event_msg / item_completed / ImageView",
          "concept": "attachment",
          "summary": "The agent viewed a local image.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"ImageView\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.path",
              "type": "string(file URI)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"ImageView\",\"id\":\"call_v\",\"path\":\"file:///home/user/project/shot.png\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L395-L401"
        },
        {
          "type": "event_msg / item_completed / ImageGeneration",
          "concept": "tool-result",
          "summary": "Hosted image generation display item.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"ImageGeneration\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.revised_prompt",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.result",
              "type": "string",
              "required": true,
              "description": "base64"
            },
            {
              "name": "item.saved_path",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"ImageGeneration\",\"id\":\"ig_1\",\"status\":\"completed\",\"result\":\"iVBORw0KGgo=\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L405-L414"
        },
        {
          "type": "event_msg / item_completed / HookPrompt",
          "concept": "hook",
          "summary": "Prompt fragments injected by hooks.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"HookPrompt\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.fragments",
              "type": "array",
              "required": true,
              "description": "[{text, hookRunId}]"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"HookPrompt\",\"id\":\"h1\",\"fragments\":[{\"text\":\"Remember to run tests.\",\"hookRunId\":\"hr1\"}]},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L102-L117"
        },
        {
          "type": "event_msg / item_completed / EnteredReviewMode",
          "concept": "turn-start",
          "summary": "Review mode started.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"EnteredReviewMode\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.target",
              "type": "object",
              "required": true,
              "description": "ReviewTarget (camelCase type)"
            },
            {
              "name": "item.user_facing_hint",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"EnteredReviewMode\",\"id\":\"r1\",\"target\":{\"type\":\"uncommittedChanges\"},\"user_facing_hint\":\"current changes\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L180-L184"
        },
        {
          "type": "event_msg / item_completed / ExitedReviewMode",
          "concept": "summary",
          "summary": "Review finished with output.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"ExitedReviewMode\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.review_output",
              "type": "object | null",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"ExitedReviewMode\",\"id\":\"r1\",\"review_output\":null},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L187-L190"
        },
        {
          "type": "event_msg / item_completed / ContextCompaction",
          "concept": "compaction",
          "summary": "Display marker for a context compaction.",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"ContextCompaction\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"ContextCompaction\",\"id\":\"0199aaaa-0000-7000-8000-000000000030\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L516-L518"
        },
        {
          "type": "event_msg / item_completed / Extension / web.search",
          "concept": "tool-result",
          "summary": "Standalone web-search extension item (camelCase).",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"Extension\""
            },
            {
              "name": "item.kind",
              "type": "string",
              "required": true,
              "description": "\"web.search\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.query",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.action",
              "type": "object | null",
              "required": true,
              "description": "{type: search|openPage|findInPage|other, ...} (camelCase)"
            },
            {
              "name": "item.results",
              "type": "any[] | null",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Extension\",\"kind\":\"web.search\",\"id\":\"ws_2\",\"query\":\"rust serde\",\"action\":{\"type\":\"search\",\"query\":\"rust serde\",\"queries\":null},\"results\":[]},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/items/src/lib.rs#L32-L46"
        },
        {
          "type": "event_msg / item_completed / Extension / clock.sleep",
          "concept": "tool-progress",
          "summary": "The agent slept/waited.",
          "when": "When the item completes within a turn.",
          "persisted": "always (both history modes)",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"Extension\""
            },
            {
              "name": "item.kind",
              "type": "string",
              "required": true,
              "description": "\"clock.sleep\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.durationMs",
              "type": "integer",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Extension\",\"kind\":\"clock.sleep\",\"id\":\"s1\",\"durationMs\":30000},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/items/src/lib.rs#L32-L46"
        },
        {
          "type": "event_msg / item_completed / Extension / image_gen.generation",
          "concept": "tool-result",
          "summary": "Standalone image-generation extension item (camelCase).",
          "when": "When the item completes within a turn.",
          "persisted": "only history_mode = paginated",
          "fields": [
            {
              "name": "item.type",
              "type": "string",
              "required": true,
              "description": "\"Extension\""
            },
            {
              "name": "item.kind",
              "type": "string",
              "required": true,
              "description": "\"image_gen.generation\""
            },
            {
              "name": "item.id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.status",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.revisedPrompt",
              "type": "string | null",
              "required": true,
              "description": "—"
            },
            {
              "name": "item.result | item.fileId",
              "type": "string",
              "required": true,
              "description": "Flattened GeneratedImageRef."
            },
            {
              "name": "item.transparentBackground",
              "type": "boolean | null",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.failure",
              "type": "object | null",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.savedPath",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "item.inputImages",
              "type": "array",
              "required": false,
              "description": "[{path, sha256}]"
            }
          ],
          "example": "{\"timestamp\":\"2026-01-02T03:04:05.678Z\",\"ordinal\":7,\"type\":\"event_msg\",\"payload\":{\"type\":\"item_completed\",\"thread_id\":\"0199aaaa-0000-7000-8000-000000000001\",\"turn_id\":\"t1\",\"item\":{\"type\":\"Extension\",\"kind\":\"image_gen.generation\",\"id\":\"ig_2\",\"status\":\"completed\",\"revisedPrompt\":\"A blue square\",\"result\":\"iVBORw0KGgo=\",\"transparentBackground\":null,\"failure\":null,\"savedPath\":\"/home/user/.codex/generated_images/thread/ig_2.png\"},\"started_at_ms\":1767323049000,\"completed_at_ms\":1767323050000}}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/ext/items/src/lib.rs#L32-L46"
        }
      ],
      "contentBlocks": [
        {
          "type": "message.content / input_text",
          "concept": "user-message",
          "summary": "Text sent to the model (user, developer, injected context).",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_text\",\"text\":\"Fix the failing test.\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L881-L910"
        },
        {
          "type": "message.content / input_image",
          "concept": "attachment",
          "summary": "Image sent to the model, inline (data URL) or by file id.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "image_url",
              "type": "string",
              "required": false,
              "description": "Data URL or URL (untagged with file_id)."
            },
            {
              "name": "file_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "detail",
              "type": "enum(auto|low|high|original)",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\",\"detail\":\"high\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L881-L910"
        },
        {
          "type": "message.content / input_audio",
          "concept": "attachment",
          "summary": "Audio sent to the model.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "audio_url",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_audio\",\"audio_url\":\"data:audio/wav;base64,UklGRg==\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L881-L910"
        },
        {
          "type": "message.content / output_text",
          "concept": "assistant-message",
          "summary": "Assistant output text.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "annotations",
              "type": "any[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "logprobs",
              "type": "any[]",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"output_text\",\"text\":\"Done.\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L881-L910"
        },
        {
          "type": "reasoning.summary / summary_text",
          "concept": "reasoning",
          "summary": "Readable reasoning summary part.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"summary_text\",\"text\":\"Inspecting the test.\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2133-L2137"
        },
        {
          "type": "reasoning.content / reasoning_text",
          "concept": "reasoning",
          "summary": "Raw reasoning text part.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"reasoning_text\",\"text\":\"...\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2139-L2144"
        },
        {
          "type": "reasoning.content / text",
          "concept": "reasoning",
          "summary": "Raw reasoning text part (alternate form).",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"...\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2139-L2144"
        },
        {
          "type": "agent_message.content / input_text",
          "concept": "user-message",
          "summary": "Plain inter-agent message text.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_text\",\"text\":\"Run the linter.\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L937-L942"
        },
        {
          "type": "agent_message.content / encrypted_content",
          "concept": "user-message",
          "summary": "Encrypted inter-agent message.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "encrypted_content",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"encrypted_content\",\"encrypted_content\":\"gAAAA...\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L937-L942"
        },
        {
          "type": "tool output (string form)",
          "concept": "tool-result",
          "summary": "function_call_output.output / custom_tool_call_output.output as a bare JSON string.",
          "when": "Inside the parent record named in type.",
          "fields": [],
          "example": "\"Process exited with code 0\"",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2418-L2428"
        },
        {
          "type": "tool output / input_text",
          "concept": "tool-result",
          "summary": "Text part of a structured tool output.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_text\",\"text\":\"ok\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2247-L2269"
        },
        {
          "type": "tool output / input_image",
          "concept": "attachment",
          "summary": "Image returned by a tool.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "image_url | file_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "detail",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2247-L2269"
        },
        {
          "type": "tool output / input_audio",
          "concept": "attachment",
          "summary": "Audio returned by a tool.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "audio_url",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"input_audio\",\"audio_url\":\"data:audio/wav;base64,UklGRg==\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2247-L2269"
        },
        {
          "type": "tool output / encrypted_content",
          "concept": "tool-result",
          "summary": "Encrypted tool output part.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "encrypted_content",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"encrypted_content\",\"encrypted_content\":\"gAAAA...\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/models.rs#L2247-L2269"
        },
        {
          "type": "UserMessage.content / text",
          "concept": "user-message",
          "summary": "User text with UI element spans.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "text_elements",
              "type": "array",
              "required": true,
              "description": "[{byte_range:{start,end}, placeholder}]"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Fix it\",\"text_elements\":[]}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L66"
        },
        {
          "type": "UserMessage.content / image",
          "concept": "attachment",
          "summary": "Image by URL/data URL or file id.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "image_url | file_id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "detail",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"image\",\"image_url\":\"data:image/png;base64,iVBORw0KGgo=\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "UserMessage.content / local_image",
          "concept": "attachment",
          "summary": "Image attached from a local path (bytes not stored in this block).",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "path",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "detail",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"local_image\",\"path\":\"/home/user/shot.png\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "UserMessage.content / audio",
          "concept": "attachment",
          "summary": "Audio by URL.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "audio_url",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"audio\",\"audio_url\":\"data:audio/wav;base64,UklGRg==\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "UserMessage.content / local_audio",
          "concept": "attachment",
          "summary": "Audio from a local path.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "path",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"local_audio\",\"path\":\"/home/user/a.wav\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "UserMessage.content / skill",
          "concept": "attachment",
          "summary": "Explicitly selected skill.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "path",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"skill\",\"name\":\"example-skill\",\"path\":\"/home/user/.codex/skills/example/SKILL.md\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "UserMessage.content / mention",
          "concept": "attachment",
          "summary": "@-mention of a resource.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "path",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"mention\",\"name\":\"README.md\",\"path\":\"README.md\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/user_input.rs#L13-L58"
        },
        {
          "type": "AgentMessage.content / Text",
          "concept": "assistant-message",
          "summary": "Display text of an AgentMessage item (PascalCase type).",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"Text\",\"text\":\"Done.\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/items.rs#L130-L134"
        },
        {
          "type": "DynamicToolCall.content_items / inputText|inputImage|inputAudio",
          "concept": "tool-result",
          "summary": "Dynamic tool output parts (camelCase type and fields).",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "text | imageUrl | audioUrl",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"inputText\",\"text\":\"ok\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/dynamic_tools.rs#L65-L75"
        },
        {
          "type": "McpToolCall.result.content / <MCP content block>",
          "concept": "tool-result",
          "summary": "Opaque MCP content blocks (text, image, resource, ...), passed through as JSON.",
          "when": "Inside the parent record named in type.",
          "fields": [
            {
              "name": "type",
              "type": "string",
              "required": true,
              "description": "MCP block type"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"result\"}",
          "reference": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/mcp.rs#L348-L362"
        }
      ],
      "linking": [
        {
          "topic": "ordering",
          "rule": "Use file order. In paginated files ordinal increases by exactly 1 per line and is the canonical position (thread_history_1.sqlite keys on it); timestamps are millisecond write times and are not unique. A record whose line fails to parse should be skipped (Codex counts and skips it), not treated as end of file."
        },
        {
          "topic": "turns",
          "rule": "A turn is bounded by event_msg task_started and task_complete or turn_aborted with the same turn_id. turn_context.turn_id, item_completed.turn_id, token_usage_record.turn_id and response_item internal_chat_message_metadata_passthrough.turn_id attach records to a turn; root_turn_id links turns caused by another (e.g. sub-agent work) back to the originating root turn. Older response items have no turn_id: assign them to the open task_started span."
        },
        {
          "topic": "message parent links",
          "rule": "There are no parent pointers between messages; the conversation is the ordered sequence of response_item records (model view) or item_completed items (display view in paginated mode). Do not merge both views: in paginated files every user/assistant message appears twice (response_item message and item_completed UserMessage/AgentMessage)."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "Pair function_call -> function_call_output, custom_tool_call -> custom_tool_call_output, tool_search_call -> tool_search_output, local_shell_call -> function_call_output by call_id. web_search_call and image_generation_call contain their own results. Display items (CommandExecution, FileChange, McpToolCall, DynamicToolCall, CollabAgentToolCall) use the tool call_id as item.id."
        },
        {
          "topic": "subagents",
          "rule": "A child thread has its own rollout. Its session_meta has parent_thread_id and source {\"subagent\":{\"thread_spawn\":{parent_thread_id, depth, agent_path, agent_nickname, agent_role}}} (review/compact sub-agents use {\"subagent\":\"review\"} etc.). Records with ordinal < subagent_history_start_ordinal are inherited parent context, not the child's own work. In the parent, CollabAgentToolCall (receiver_thread_ids) and SubAgentActivity (agent_thread_id) point to children; state_5.sqlite thread_spawn_edges indexes the edges. session_id is the root thread id for the whole tree."
        },
        {
          "topic": "forks",
          "rule": "forked_from_id names the source thread. Legacy: the parent's records are copied into the child file, possibly including the parent's session_meta lines (only the first session_meta is the file's own). Paginated: history_base {thread_id = source ROLLOUT id, end_ordinal_exclusive, end_byte_offset} points at an immutable prefix; resolve it recursively and prepend the source rollout's records with ordinal in [start, end_ordinal_exclusive), where start is 1 for a root file and base.end_ordinal_exclusive+1 for a file that itself has a history_base (skipping each file's own session_meta)."
        },
        {
          "topic": "compaction",
          "rule": "A compacted record whose replacement_history is present is a complete new model history: discard earlier model-history items and continue from replacement_history plus later lines. Older compacted records without replacement_history require replaying earlier items and inserting the message summary. response_item compaction / context_compaction are opaque encrypted items that stand in for summarized history. item_completed ContextCompaction and legacy event_msg context_compacted are display markers only. Only the newest compaction bounds replay."
        },
        {
          "topic": "resume",
          "rule": "Resume appends to the same rollout file (no new session_meta, ordinals continue from the last line). A compressed file is first decompressed to .jsonl and the .zst removed."
        },
        {
          "topic": "branches/rewind",
          "rule": "event_msg thread_rolled_back {num_turns}: drop the last num_turns user turns (segments containing a real user message) from the reconstructed history; the dropped records remain in the file. thread/revert instead writes a new rollout file <thread-id>_<rollout-id> whose history_base points at the retained prefix; the old file is untouched and state_5.sqlite threads.rollout_path is the only pointer to the current one."
        },
        {
          "topic": "sidecar references",
          "rule": "Thread names: last session_index.jsonl entry for the id (state_5 threads.name/title may also hold it). Current rollout path, archive state and titles: state_5.sqlite threads. Paginated page projection: thread_history_1.sqlite keyed by (thread_id, rollout_ordinal). Generated images: saved_path / savedPath. local_image blocks reference paths only; image bytes are present only in inline data URLs."
        }
      ],
      "versioning": "There is no schema version field. Signals: session_meta.payload.history_mode (absent = legacy, \"paginated\" = ordinals present and a different event persistence policy); presence of envelope ordinal; session_meta.cli_version records only the build that created the thread and is preserved by the in-place legacy->paginated migration, so it does not identify the writer of later lines. Older shapes that Codex 0.164.0 still reads: task_started/task_complete accept turn_started/turn_complete aliases; response_item compaction accepts compaction_summary; agent_type -> agent_role; session_id backfilled from id; compacted.window_id may be a legacy integer; ghost_snapshot response items (removed feature) are stripped on read; content_item_metadata legacy harness_injected/source_tool_namespace forms are mapped; dynamic_tools legacy flat camelCase shape accepted; ItemCompleted.completed_at_ms defaults to 0; TurnContext fields such as user_instructions, personality, current_date, timezone, workspace_roots were dropped and are ignored.",
      "usage": [
        {
          "field": "token_usage_record.payload.usage",
          "meaning": "Tokens for exactly one Responses API response (response_id). Sum these for exact per-response accounting."
        },
        {
          "field": "token_usage_record.payload.turn_token_usage / thread_token_usage",
          "meaning": "Running totals for the turn / the thread at that response; take the last value, do not sum."
        },
        {
          "field": "event_msg token_count.payload.info.total_token_usage",
          "meaning": "Cumulative thread usage (same TokenUsage shape); last_token_usage is the latest response. info may be null; events can repeat. After a context-window overflow Codex can synthesize a filled total (total_tokens = model_context_window), which is not provider-reported usage."
        },
        {
          "field": "TokenUsage.input_tokens",
          "meaning": "Prompt tokens including cached ones."
        },
        {
          "field": "TokenUsage.cached_input_tokens",
          "meaning": "Subset of input_tokens served from cache (non-cached = input - cached)."
        },
        {
          "field": "TokenUsage.cache_write_input_tokens",
          "meaning": "Input tokens written to cache; defaults to 0 when absent (older records lack it)."
        },
        {
          "field": "TokenUsage.output_tokens",
          "meaning": "Completion tokens; reasoning_output_tokens is the reasoning portion of them."
        },
        {
          "field": "TokenUsage.total_tokens",
          "meaning": "input_tokens + output_tokens as reported."
        },
        {
          "field": "token_count.payload.info.model_context_window / task_started.model_context_window",
          "meaning": "Context window size in tokens for the model."
        },
        {
          "field": "token_count.payload.rate_limits",
          "meaning": "Plan rate-limit snapshot (used_percent, window_minutes, resets_at, credits); not a cost. No monetary cost is recorded anywhere in the rollout."
        }
      ],
      "gotchas": [
        "Paginated files (the default for current builds, and legacy files after the startup migration) persist BOTH the model view (response_item) and the display view (event_msg item_completed); counting both double-counts every message and tool call.",
        "Legacy and paginated files persist different event_msg sets: user_message/agent_message/agent_reasoning/etc. exist only in legacy files; most item_completed variants exist only in paginated files.",
        "TurnItem types are PascalCase (\"UserMessage\", \"CommandExecution\") and Extension items add a second discriminator kind (\"web.search\", \"clock.sleep\", \"image_gen.generation\"); everything else uses snake_case.",
        "Field casing is mixed: McpToolCall items, extension items, thread_goal_updated, ReviewTarget and dynamic-tool content items are camelCase; the rest is snake_case.",
        "Rollout directory and filename timestamps are local time; session_meta.timestamp and line timestamps are UTC.",
        "function_call.arguments is a JSON-encoded string; tool_search_call.arguments is a JSON value.",
        "Tool outputs are either a bare string or an array of content items; the success flag is never serialized.",
        "Durations are Rust Duration objects {secs, nanos}; mcp_tool_call_end.result is a Rust Result {\"Ok\":...}|{\"Err\":...}.",
        "role=user response_item messages include harness-injected context (AGENTS.md, environment_context, skills), not just what the human typed; use item_completed UserMessage (paginated) or event_msg user_message (legacy) for the human's input.",
        "Reasoning is mostly encrypted_content; only summary[] (and occasionally content[]) is readable.",
        "Unparseable lines occur mid-file; skip them and continue.",
        "Legacy forks contain copied parent records including parent session_meta lines; only the first session_meta describes the file.",
        "A thread can have several rollout files after revert; only state_5.sqlite threads.rollout_path identifies the current one. Paginated forks/reverts need history_base resolution to see the inherited prefix.",
        "Files are compressed to .jsonl.zst after 7 idle days and decompressed again on resume, so the same thread's path extension changes over time.",
        "cli_version is the creating build, not the writer; migrated legacy rollouts look paginated while claiming old versions.",
        "Large outputs: CommandExecution.aggregated_output and McpToolCall.result in paginated item_completed are truncated to 64 KiB, but the matching response_item output may be complete (or separately truncated by the model-history budget).",
        "image_generation_call.result and inline input_image data URLs can be megabytes of base64 on a single line.",
        "Not persisted in either mode (never on disk): response_item compaction_trigger and unknown response types (Other); event_msg error, warning, guardian_warning, guardian_assessment, auth_recovery_started/completed, thread_queue_changed, realtime_conversation_started/realtime/closed/sdp/list_voices_response, model_reroute, model_verification, turn_moderation_metadata, safety_buffering, agent_reasoning_section_break, raw_response_item, raw_response_completed, session_configured, environment_connected/disconnected, mcp_startup_update/complete, mcp_tool_call_begin, web_search_begin, image_generation_begin, exec_command_begin/output_delta/end, terminal_interaction, view_image_tool_call, exec_approval_request, request_permissions, request_user_input, dynamic_tool_call_request/response, elicitation_request/abandoned, apply_patch_approval_request, deprecation_notice, stream_error, patch_apply_begin/updated, turn_diff, plan_update, shutdown_complete, item_started, hook_started/completed, agent_message_content_delta, plan_delta, reasoning_content_delta, reasoning_raw_content_delta, collab_agent_spawn/interaction/waiting/close/resume begin+end. Approvals, hooks runs and errors therefore leave no dedicated record (only their effects, e.g. a declined CommandExecution status or a task_complete.error). Source: https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/rollout/src/policy.rs#L127-L226"
      ],
      "evidence": [
        "transcript-format-codex-codex-rs-core-src-session-rollout-reconstruction-rs",
        "transcript-format-codex-codex-rs-core-src-shell-snapshot-rs",
        "transcript-format-codex-codex-rs-ext-items-src-lib-rs",
        "transcript-format-codex-codex-rs-history-src-lib-rs",
        "transcript-format-codex-codex-rs-history-src-retained-context-rs",
        "transcript-format-codex-codex-rs-history-src-rollout-payload-rs",
        "transcript-format-codex-codex-rs-message-history-src-lib-rs",
        "transcript-format-codex-codex-rs-protocol-src-dynamic-tools-rs",
        "transcript-format-codex-codex-rs-protocol-src-items-rs",
        "transcript-format-codex-codex-rs-protocol-src-mcp-rs",
        "transcript-format-codex-codex-rs-protocol-src-models-rs",
        "transcript-format-codex-codex-rs-protocol-src-protocol-rs",
        "transcript-format-codex-codex-rs-protocol-src-realtime-rs",
        "transcript-format-codex-codex-rs-protocol-src-security-risk-rs",
        "transcript-format-codex-codex-rs-protocol-src-user-input-rs",
        "transcript-format-codex-codex-rs-rollout-src-compression-rs",
        "transcript-format-codex-codex-rs-rollout-src-ordinal-rs",
        "transcript-format-codex-codex-rs-rollout-src-policy-rs",
        "transcript-format-codex-codex-rs-rollout-src-recorder-rs",
        "transcript-format-codex-codex-rs-rollout-src-rollout-file-name-rs",
        "transcript-format-codex-codex-rs-rollout-src-session-index-rs",
        "transcript-format-codex-codex-rs-rollout-src-writer-lock-rs",
        "transcript-format-codex-codex-rs-state-src-sqlite-rs",
        "transcript-format-codex-codex-rs-thread-store-src-local-archive-thread-rs",
        "transcript-format-codex-codex-rs-thread-store-src-local-revert-thread-rs",
        "transcript-format-codex-codex-rs-thread-store-src-local-rollout-lineage-rs",
        "transcript-format-codex-codex-rs-thread-store-src-local-rollout-migration-publish-rs",
        "transcript-format-codex-codex-rs-thread-store-src-local-rollout-migration-startup-rs"
      ],
      "references": {
        "location": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/rollout/src/recorder.rs#L1755-L1776",
        "records": "https://github.com/openai/codex/blob/6aaac694803004a63c6f393d153c96d22521a6b9/codex-rs/protocol/src/protocol.rs#L3256-L3330"
      }
    },
    {
      "harness": "claude-code",
      "variant": "current",
      "default": true,
      "version": "2.1.310",
      "stability": "documented-internal",
      "container": "JSON Lines, one record per line, append-only and uncompressed. Lines can be several megabytes when they carry base64 images. The final line may be cut off while the session is still writing.",
      "discriminator": "`type`, then `subtype` for `system` records and `attachment.type` for `attachment` records. Message content blocks are typed by `message.content[].type`.",
      "layout": [
        {
          "path": "~/.claude/projects/<project-key>/",
          "kind": "other",
          "description": "Per-project directory. <project-key> = absolute cwd with every non-alphanumeric char replaced by '-' (long names truncated + hash). Overridable by CLAUDE_CONFIG_DIR and CLAUDE_CODE_PROJECT_DIR_NAME (2.1.234)."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>.jsonl",
          "kind": "transcript",
          "description": "Main session transcript: append-only JSONL, one record per line, conversation + metadata records."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/subagents/agent-<agent-id>.jsonl",
          "kind": "transcript",
          "description": "Subagent (Agent tool, forked skill, workflow agent) transcript. Same record format; isSidechain:true, agentId set, sessionId = parent session. It can also hold extra nested directories between subagents/ and the file."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/subagents/agent-<agent-id>.meta.json",
          "kind": "sidecar",
          "description": "Subagent launch metadata: agentType, description, toolUseId (Agent tool_use id in the parent), spawnDepth, requestShape, requestNonInteractive, and optional isBuiltIn, launchedWithDefaults, finished, stoppedByUser, isFork, model, name, spawnedWithWorktree, worktreePath, worktreeBranch, worktreeCleanlyRemoved."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/subagents/agent-<agent-id>.forked-skill.json",
          "kind": "sidecar",
          "description": "Forked-skill scoping record {skillName, attributionName} for a subagent spawned by a context:fork skill."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/subagents/agent-<agent-id>.forked-skill.marker.json",
          "kind": "sidecar",
          "description": "Marker {forkedSkill:true, skillName}."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/tool-results/<id>.txt",
          "kind": "blob-store",
          "description": "Full output of large tool results (Bash/PowerShell output files, large MCP results) moved out of the transcript; the transcript keeps a <persisted-output> preview and toolUseResult.persistedOutputPath/persistedOutputSize. <id> is a 9-char task/output id or a toolu_ id."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>/remote-agents/remote-agent-<id>.meta.json",
          "kind": "sidecar",
          "description": "Metadata for remote (cloud) agents launched from the session."
        },
        {
          "path": "~/.claude/projects/<project-key>/<session-id>.ccr-tip.json | .precompact.json | .dir-sync.json",
          "kind": "sidecar",
          "description": "Project-level sibling files reserved per session by the storage layer (cloud-resume tip, pre-compaction copy, cloud session dir-sync record)."
        },
        {
          "path": "~/.claude/projects/<project-key>/sessions-index.json",
          "kind": "index",
          "description": "Legacy per-project session index {version, originalPath, entries[{sessionId, fullPath, fileMtime, firstPrompt, summary, messageCount, created, modified, gitBranch, projectPath, isSidechain}]}. No longer written by current versions."
        },
        {
          "path": "~/.claude/projects/<project-key>/memory/",
          "kind": "other",
          "description": "Auto-memory markdown files for the project (not per session)."
        },
        {
          "path": "~/.claude/file-history/<session-id>/<16-hex>@v<n>",
          "kind": "blob-store",
          "description": "Checkpoint backups of edited files, named by path hash + version; referenced by file-history-snapshot/delta backupFileName. Used by /rewind."
        },
        {
          "path": "~/.claude/history.jsonl",
          "kind": "history",
          "description": "Global prompt history (up-arrow / Ctrl+R): one line per submitted prompt {display, pastedContents{<id>:{id,type,content|contentHash}}, project, sessionId, timestamp(ms)}. Large pastes store contentHash referencing ~/.claude/paste-cache/<hash>.txt."
        },
        {
          "path": "~/.claude/paste-cache/<hash>.txt",
          "kind": "blob-store",
          "description": "Pasted text bodies referenced from history.jsonl pastedContents[].contentHash."
        },
        {
          "path": "~/.claude/sessions/<pid>.json",
          "kind": "other",
          "description": "Live-process registry for running sessions {pid, sessionId, cwd, startedAt, version, entrypoint, kind, name, status, ...} (+ <pid>.<hex>.key). Not a transcript."
        },
        {
          "path": "~/.claude/session-env/<session-id>/",
          "kind": "other",
          "description": "Per-session environment scripts captured from SessionStart hooks (e.g. sessionstart-hook-<n>.sh)."
        },
        {
          "path": "~/.claude/shell-snapshots/, ~/.claude/debug/, ~/.claude/todos|tasks/, ~/.claude/backups/",
          "kind": "other",
          "description": "Shell snapshots, debug logs and task state swept by cleanupPeriodDays; not part of the transcript format."
        }
      ],
      "envelope": [
        {
          "name": "type",
          "type": "string",
          "required": true,
          "description": "Record discriminator. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "uuid",
          "type": "string",
          "required": true,
          "description": "Unique id of this transcript node (UUID v4). Target of parentUuid links. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "parentUuid",
          "type": "string|null",
          "required": true,
          "description": "uuid of the preceding node in the conversation DAG; null for a chain root (first entry, compact boundary, subagent first entry). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "logicalParentUuid",
          "type": "string",
          "required": false,
          "description": "On compact_boundary: the uuid of the last pre-compaction node, preserving logical continuity while parentUuid is null. Only on system/compact_boundary. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "isSidechain",
          "type": "boolean",
          "required": true,
          "description": "true for entries belonging to a subagent (all lines in subagents/agent-*.jsonl); false in the main transcript. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "sessionId",
          "type": "string",
          "required": true,
          "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "session_id",
          "type": "string",
          "required": false,
          "description": "Duplicate snake_case session id stamped on some records (Values include on assistant/user/attachment/stop_hook_summary). Same value as sessionId. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "timestamp",
          "type": "string",
          "required": true,
          "description": "ISO-8601 UTC write time. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "version",
          "type": "string",
          "required": true,
          "description": "Claude Code version string that wrote the entry (semver). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "cwd",
          "type": "string",
          "required": true,
          "description": "Working directory at the time the entry was written (private; absolute path). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "gitBranch",
          "type": "string",
          "required": false,
          "description": "Git branch of cwd when written ('' or 'HEAD' outside a branch). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "userType",
          "type": "string",
          "required": true,
          "description": "Account class; 'external' for public users ('ant' is internal). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "entrypoint",
          "type": "string",
          "required": false,
          "description": "How Claude Code was launched (`cli`, or sdk/desktop/remote entrypoints).. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "slug",
          "type": "string",
          "required": false,
          "description": "Human-readable session slug (three-word style). Present on a subset of entries. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "agentId",
          "type": "string",
          "required": false,
          "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "isMeta",
          "type": "boolean",
          "required": false,
          "description": "true for system-injected entries not typed by the user (caveats, reminders, hook output, notices). Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "promptId",
          "type": "string",
          "required": false,
          "description": "Id grouping all entries produced in response to one user prompt. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        },
        {
          "name": "requestId",
          "type": "string",
          "required": false,
          "description": "Anthropic API request id ('req_...') of the response this assistant line came from. Applies to conversation records (user, assistant, system, attachment, legacy progress); metadata records carry only type + their own fields + usually sessionId."
        }
      ],
      "records": [
        {
          "type": "user",
          "concept": "user-message",
          "summary": "A user-role message: a typed prompt, a slash-command expansion, injected meta text, or (most often) one tool_result answering a tool_use.",
          "when": "On prompt submit; after every tool execution (one line per tool_result); for meta/caveat injections and compaction summaries.",
          "fields": [
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "cwd",
              "type": "string",
              "required": true,
              "description": "Working directory at the time the entry was written (private; absolute path)."
            },
            {
              "name": "entrypoint",
              "type": "string",
              "required": true,
              "description": "How Claude Code was launched (`cli`, or sdk/desktop/remote entrypoints)."
            },
            {
              "name": "gitBranch",
              "type": "string",
              "required": true,
              "description": "Git branch of cwd when written ('' or 'HEAD' outside a branch)."
            },
            {
              "name": "imagePasteIds",
              "type": "array",
              "required": false,
              "description": "Ids of pasted images referenced by the prompt (history pastedContents ids).",
              "since": "2.1.302"
            },
            {
              "name": "imagePasteIds[]",
              "type": "number",
              "required": false,
              "description": "Ids of pasted images referenced by the prompt (history pastedContents ids).",
              "since": "2.1.302"
            },
            {
              "name": "interruptedMessageId",
              "type": "string",
              "required": false,
              "description": "message.id of an assistant response that was interrupted by this user entry."
            },
            {
              "name": "isCompactSummary",
              "type": "boolean",
              "required": false,
              "description": "true on the user entry that carries the compaction summary text."
            },
            {
              "name": "isMeta",
              "type": "boolean",
              "required": false,
              "description": "true for system-injected entries not typed by the user (caveats, reminders, hook output, notices)."
            },
            {
              "name": "isSidechain",
              "type": "boolean",
              "required": true,
              "description": "true for entries belonging to a subagent (all lines in subagents/agent-*.jsonl); false in the main transcript."
            },
            {
              "name": "isVisibleInTranscriptOnly",
              "type": "boolean",
              "required": false,
              "description": "true when the entry is shown in the transcript view but not sent to the model as-is (compact summary)."
            },
            {
              "name": "mcpMeta",
              "type": "object",
              "required": false,
              "description": "MCP tool-result metadata: {_meta?, structuredContent?} copied from the MCP CallToolResult."
            },
            {
              "name": "mcpMeta._meta",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "mcpMeta.structuredContent",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message",
              "type": "object",
              "required": true,
              "description": "Anthropic Messages API message object (role + content + for assistant: id/model/usage/stop fields)."
            },
            {
              "name": "message.content",
              "type": "string|array",
              "required": true,
              "description": "String (plain prompt or command output) or array of content blocks; see contentBlocks."
            },
            {
              "name": "message.role",
              "type": "string",
              "required": true,
              "description": "Message role. Values include: user."
            },
            {
              "name": "origin",
              "type": "object",
              "required": false,
              "description": "Provenance of a non-typed or queued prompt: {kind, name?, from?, body?, producer?, runId?, senderTaskId?, handback?, handbackReportText?}."
            },
            {
              "name": "origin.body",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "origin.from",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "origin.handback",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "origin.handbackReportText",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.300"
            },
            {
              "name": "origin.kind",
              "type": "string",
              "required": false,
              "description": "Values include: human, peer, task-notification, coordinator."
            },
            {
              "name": "origin.name",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.288"
            },
            {
              "name": "origin.producer",
              "type": "string",
              "required": false,
              "description": "Values include: session-task."
            },
            {
              "name": "origin.runId",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.293"
            },
            {
              "name": "origin.senderTaskId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "parentUuid",
              "type": "string|null",
              "required": true,
              "description": "uuid of the preceding node in the conversation DAG; null for a chain root (first entry, compact boundary, subagent first entry)."
            },
            {
              "name": "permissionDecision",
              "type": "object",
              "required": false,
              "description": "Permission decision for the tool call answered by this tool_result: {decision accept|reject, source, reasonType, reasonCode?, ruleSource?, grantScope?, classifierCategory?}.",
              "since": "2.1.293"
            },
            {
              "name": "permissionDecision.classifierCategory",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.309"
            },
            {
              "name": "permissionDecision.decision",
              "type": "string",
              "required": false,
              "description": "Values include: accept, reject.",
              "since": "2.1.293"
            },
            {
              "name": "permissionDecision.grantScope",
              "type": "string",
              "required": false,
              "description": "Values include: once.",
              "since": "2.1.307"
            },
            {
              "name": "permissionDecision.reasonCode",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.307"
            },
            {
              "name": "permissionDecision.reasonType",
              "type": "string",
              "required": false,
              "description": "Values include: classifier, mode, other, rule, subcommandResults, safetyCheck.",
              "since": "2.1.293"
            },
            {
              "name": "permissionDecision.ruleSource",
              "type": "string",
              "required": false,
              "description": "Values include: localSettings.",
              "since": "2.1.307"
            },
            {
              "name": "permissionDecision.source",
              "type": "string",
              "required": false,
              "description": "Values include: config, user_temporary, user_reject.",
              "since": "2.1.293"
            },
            {
              "name": "permissionMode",
              "type": "string",
              "required": false,
              "description": "Permission mode in force when the prompt was submitted (default/acceptEdits/plan/auto/bypassPermissions...). Values include: auto."
            },
            {
              "name": "promptId",
              "type": "string",
              "required": false,
              "description": "Id grouping all entries produced in response to one user prompt."
            },
            {
              "name": "promptSource",
              "type": "string",
              "required": false,
              "description": "How the prompt arrived (typed, queued, system...). Values include: typed, system, queued."
            },
            {
              "name": "queueSkipAttachments",
              "type": "boolean",
              "required": false,
              "description": "Queued prompt delivered without re-running attachment collection."
            },
            {
              "name": "queueSkipSlashCommands",
              "type": "boolean",
              "required": false,
              "description": "Queued prompt delivered without slash-command expansion.",
              "since": "2.1.300"
            },
            {
              "name": "queueTranscriptOnly",
              "type": "boolean",
              "required": false,
              "description": "Queued prompt recorded in the transcript only.",
              "since": "2.1.296"
            },
            {
              "name": "repeatsCompactSummary",
              "type": "boolean",
              "required": false,
              "description": "Entry repeats an earlier compact summary.",
              "since": "2.1.296"
            },
            {
              "name": "sandboxed",
              "type": "boolean",
              "required": false,
              "description": "Whether the tool call ran under the OS sandbox.",
              "since": "2.1.307"
            },
            {
              "name": "serverClassifierContext",
              "type": "object",
              "required": false,
              "description": "Auto-mode safety-classifier context sent with the request: {request, context:{git_state, live_cwd, platform}}."
            },
            {
              "name": "serverClassifierContext.context",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "serverClassifierContext.context.git_state",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "serverClassifierContext.context.live_cwd",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "serverClassifierContext.context.platform",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "serverClassifierContext.request",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "session_id",
              "type": "string",
              "required": false,
              "description": "Duplicate snake_case session id stamped on some records (Values include on assistant/user/attachment/stop_hook_summary). Same value as sessionId."
            },
            {
              "name": "slug",
              "type": "string",
              "required": false,
              "description": "Human-readable session slug (three-word style). Present on a subset of entries."
            },
            {
              "name": "sourceToolAssistantUUID",
              "type": "string",
              "required": false,
              "description": "uuid of the assistant line containing the tool_use this tool_result answers."
            },
            {
              "name": "sourceToolUseID",
              "type": "string",
              "required": false,
              "description": "tool_use id that caused this entry (e.g. skill/command expansion)."
            },
            {
              "name": "summarizedTurnPromptUuids",
              "type": "array",
              "required": false,
              "description": "Prompt uuids folded into a summarize-from-here (/rewind summarize) entry.",
              "since": "2.1.305"
            },
            {
              "name": "summarizedTurnPromptUuids[]",
              "type": "string",
              "required": false,
              "description": "Prompt uuids folded into a summarize-from-here (/rewind summarize) entry.",
              "since": "2.1.305"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "toolDenialKind",
              "type": "string",
              "required": false,
              "description": "Why a tool call was denied (user-rejected, automode-blocked, permission-rule, automode-unavailable...). Values include: user-rejected, automode-blocked, permission-rule, automode-unavailable."
            },
            {
              "name": "toolEndsTurn",
              "type": "boolean",
              "required": false,
              "description": "The tool result ends the turn (e.g. handback).",
              "since": "2.1.288"
            },
            {
              "name": "turnCompanion",
              "type": "boolean",
              "required": false,
              "description": "Entry accompanies a turn without being a turn itself."
            },
            {
              "name": "turnOrigin",
              "type": "string",
              "required": false,
              "description": "Origin of the turn (human, peer, task_notification...). Values include: human, peer, task_notification."
            },
            {
              "name": "turnPosition",
              "type": "object",
              "required": false,
              "description": "{promptIndex, turnIndex} position of a human turn."
            },
            {
              "name": "turnPosition.promptIndex",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "turnPosition.turnIndex",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "userFeedback",
              "type": "string",
              "required": false,
              "description": "Free-text feedback attached to a rejection.",
              "since": "2.1.296"
            },
            {
              "name": "userType",
              "type": "string",
              "required": true,
              "description": "Account class; 'external' for public users ('ant' is internal). Values include: external."
            },
            {
              "name": "uuid",
              "type": "string",
              "required": true,
              "description": "Unique id of this transcript node (UUID v4). Target of parentUuid links."
            },
            {
              "name": "version",
              "type": "string",
              "required": true,
              "description": "Claude Code version string that wrote the entry (semver)."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"user\",\"promptId\":\"33333333-3333-4333-8333-333333333333\",\"message\":{\"role\":\"user\",\"content\":\"Add a README section on setup.\"},\"permissionMode\":\"default\",\"promptSource\":\"typed\",\"turnOrigin\":\"human\"}",
          "notes": [
            "Tool-result user lines carry message.content=[{type:tool_result,...}], plus toolUseResult and sourceToolAssistantUUID.",
            "message.content is a plain string for typed prompts and command output and an array otherwise.",
            "Fields omitted at depth >2 under mcpMeta.structuredContent are MCP-server-specific and pass through unchanged.",
            "Other user fields that can appear include replacesSpan, forkedFrom {sessionId,messageUuid}, sessionKind, isVirtual, virtualInResumeRun, resumedFromIncompleteThinking (assistant)."
          ]
        },
        {
          "type": "assistant",
          "concept": "assistant-message",
          "summary": "One content block of a model response. A streamed response with N content blocks is written as N lines that share message.id and requestId.",
          "when": "As each content block of an API response completes (thinking, text, tool_use).",
          "fields": [
            {
              "name": "advisorModel",
              "type": "string",
              "required": false,
              "description": "Advisor (server-side advisor tool) model id configured for this response."
            },
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "apiBlockIndex",
              "type": "number",
              "required": false,
              "description": "Index of this line's content block within the streamed API response (0-based)."
            },
            {
              "name": "attributionAgent",
              "type": "string",
              "required": false,
              "description": "Agent type attribution for the response (for subagents)."
            },
            {
              "name": "attributionMcpServer",
              "type": "string",
              "required": false,
              "description": "MCP server attribution for the response."
            },
            {
              "name": "attributionMcpTool",
              "type": "string",
              "required": false,
              "description": "MCP tool attribution."
            },
            {
              "name": "attributionPlugin",
              "type": "string",
              "required": false,
              "description": "Plugin attribution.",
              "since": "2.1.310"
            },
            {
              "name": "attributionSkill",
              "type": "string",
              "required": false,
              "description": "Skill attribution."
            },
            {
              "name": "cwd",
              "type": "string",
              "required": true,
              "description": "Working directory at the time the entry was written (private; absolute path)."
            },
            {
              "name": "effort",
              "type": "string",
              "required": false,
              "description": "Effort level of the request (low/medium/high/xhigh/max). Values include: medium."
            },
            {
              "name": "entrypoint",
              "type": "string",
              "required": true,
              "description": "How Claude Code was launched (`cli`, or sdk/desktop/remote entrypoints)."
            },
            {
              "name": "error",
              "type": "string",
              "required": false,
              "description": "API error class on a synthetic error assistant message (server_error, authentication_failed, rate_limit...). Values include: server_error, authentication_failed."
            },
            {
              "name": "gitBranch",
              "type": "string",
              "required": true,
              "description": "Git branch of cwd when written ('' or 'HEAD' outside a branch)."
            },
            {
              "name": "isApiErrorMessage",
              "type": "boolean",
              "required": false,
              "description": "true on a synthetic assistant message that reports an API error."
            },
            {
              "name": "isSidechain",
              "type": "boolean",
              "required": true,
              "description": "true for entries belonging to a subagent (all lines in subagents/agent-*.jsonl); false in the main transcript."
            },
            {
              "name": "message",
              "type": "object",
              "required": true,
              "description": "Anthropic Messages API message object (role + content + for assistant: id/model/usage/stop fields)."
            },
            {
              "name": "message.container",
              "type": "null",
              "required": true,
              "description": "API container field (null)."
            },
            {
              "name": "message.content",
              "type": "array",
              "required": true,
              "description": "String (plain prompt or command output) or array of content blocks; see contentBlocks."
            },
            {
              "name": "message.context_management",
              "type": "null",
              "required": true,
              "description": "API context-management response field (null when no edits applied)."
            },
            {
              "name": "message.diagnostics",
              "type": "null|object",
              "required": true,
              "description": "API diagnostics; cache_miss_reason {type, cache_missed_input_tokens} when the prompt cache missed."
            },
            {
              "name": "message.diagnostics.cache_miss_reason",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.diagnostics.cache_miss_reason.cache_missed_input_tokens",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.diagnostics.cache_miss_reason.type",
              "type": "string",
              "required": false,
              "description": "Record discriminator. Values include: tools_changed, previous_message_not_found, unavailable, messages_changed."
            },
            {
              "name": "message.id",
              "type": "string",
              "required": true,
              "description": "API message id ('msg_...'). Shared by every line split from one streamed response."
            },
            {
              "name": "message.input_transformations",
              "type": "array",
              "required": false,
              "description": "Client-side transformations applied to the request input, e.g. {type:thinking_dropped, reason:prefix_binding_mismatch, path}."
            },
            {
              "name": "message.input_transformations[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.input_transformations[].path",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.input_transformations[].reason",
              "type": "string",
              "required": false,
              "description": "Values include: prefix_binding_mismatch."
            },
            {
              "name": "message.input_transformations[].type",
              "type": "string",
              "required": false,
              "description": "Record discriminator. Values include: thinking_dropped."
            },
            {
              "name": "message.model",
              "type": "string",
              "required": true,
              "description": "Model id that produced the response. Values include: claude-opus-5-5, claude-sonnet-5-5."
            },
            {
              "name": "message.role",
              "type": "string",
              "required": true,
              "description": "Message role. Values include: assistant."
            },
            {
              "name": "message.stop_details",
              "type": "null",
              "required": true,
              "description": "API stop details object or null."
            },
            {
              "name": "message.stop_reason",
              "type": "string|null",
              "required": true,
              "description": "API stop reason (tool_use, end_turn, stop_sequence, max_tokens, refusal...). null in some subagent transcripts before 2.1.307 (placeholder bug). Values include: tool_use, end_turn, stop_sequence."
            },
            {
              "name": "message.stop_sequence",
              "type": "null|string",
              "required": true,
              "description": "Matched stop sequence or null."
            },
            {
              "name": "message.type",
              "type": "string",
              "required": true,
              "description": "Always 'message'. Values include: message."
            },
            {
              "name": "message.usage",
              "type": "object",
              "required": true,
              "description": "Token usage for the whole API response (repeated identically on every split line)."
            },
            {
              "name": "message.usage.cache_creation",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.cache_creation.ephemeral_1h_input_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.cache_creation.ephemeral_5m_input_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.cache_creation_input_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.cache_read_input_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.fallback_credit",
              "type": "null",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "message.usage.inference_geo",
              "type": "string|null",
              "required": true,
              "description": "Values include: global, not_available."
            },
            {
              "name": "message.usage.input_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.iterations",
              "type": "array|null",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.iterations[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.output_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.usage.output_tokens_details",
              "type": "object|null",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.output_tokens_details.thinking_tokens",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.server_tool_use",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.server_tool_use.web_fetch_requests",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.server_tool_use.web_search_requests",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.usage.service_tier",
              "type": "string|null",
              "required": true,
              "description": "Values include: standard."
            },
            {
              "name": "message.usage.speed",
              "type": "string|null",
              "required": false,
              "description": "Values include: standard."
            },
            {
              "name": "parentUuid",
              "type": "string|null",
              "required": true,
              "description": "uuid of the preceding node in the conversation DAG; null for a chain root (first entry, compact boundary, subagent first entry)."
            },
            {
              "name": "perTurnEffort",
              "type": "string",
              "required": false,
              "description": "Effort level chosen for this turn. Values include: medium."
            },
            {
              "name": "requestId",
              "type": "string",
              "required": false,
              "description": "Anthropic API request id ('req_...') of the response this assistant line came from."
            },
            {
              "name": "requestRef",
              "type": "string",
              "required": false,
              "description": "id of the api-request record that produced this response (since 2.1.300).",
              "since": "2.1.300"
            },
            {
              "name": "requestedModel",
              "type": "string",
              "required": false,
              "description": "Model requested before any fallback/alias resolution.",
              "since": "2.1.295"
            },
            {
              "name": "serverClassifierRequest",
              "type": "string",
              "required": false,
              "description": "Opaque classifier request reference on assistant lines."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "session_id",
              "type": "string",
              "required": false,
              "description": "Duplicate snake_case session id stamped on some records (Values include on assistant/user/attachment/stop_hook_summary). Same value as sessionId."
            },
            {
              "name": "slug",
              "type": "string",
              "required": false,
              "description": "Human-readable session slug (three-word style). Present on a subset of entries."
            },
            {
              "name": "thinkingDisplay",
              "type": "string",
              "required": false,
              "description": "Thinking display mode ('updates' = thinking text summarised/omitted, signature kept). Values include: updates.",
              "since": "2.1.296"
            },
            {
              "name": "thinkingDurationMs",
              "type": "number",
              "required": false,
              "description": "Wall time spent in thinking for this response.",
              "since": "2.1.287"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "truncatedAfterOutput",
              "type": "boolean",
              "required": false,
              "description": "Response truncated after output was produced.",
              "since": "2.1.302"
            },
            {
              "name": "userType",
              "type": "string",
              "required": true,
              "description": "Account class; 'external' for public users ('ant' is internal). Values include: external."
            },
            {
              "name": "uuid",
              "type": "string",
              "required": true,
              "description": "Unique id of this transcript node (UUID v4). Target of parentUuid links."
            },
            {
              "name": "version",
              "type": "string",
              "required": true,
              "description": "Claude Code version string that wrote the entry (semver)."
            },
            {
              "name": "wireIngestContext",
              "type": "object",
              "required": false,
              "description": "Map tool_use id -> {cwd} context captured when the tool input was ingested."
            },
            {
              "name": "wireIngestContext.<dynamic-key>",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "wireIngestContext.<dynamic-key>.cwd",
              "type": "string",
              "required": false,
              "description": "Working directory at the time the entry was written (private; absolute path)."
            },
            {
              "name": "wireToolInputs",
              "type": "object",
              "required": false,
              "description": "Map tool_use id -> the exact input object as sent on the wire, when it differs from message.content tool_use input (normalised/echoed inputs)."
            }
          ],
          "example": "{\"parentUuid\":\"22222222-2222-4222-8222-222222222222\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"44444444-4444-4444-8444-444444444444\",\"type\":\"assistant\",\"requestId\":\"req_011Example\",\"message\":{\"id\":\"msg_01Example\",\"type\":\"message\",\"role\":\"assistant\",\"model\":\"claude-opus-5-5\",\"content\":[{\"type\":\"text\",\"text\":\"Done.\"}],\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":10,\"output_tokens\":5,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":1200}}}",
          "notes": [
            "A streamed response is split across lines that share `message.id`. Every split line holds exactly one content block, the same requestId, identical usage and the same stop_reason.",
            "wireToolInputs keys and tool inputs are tool-specific; only top-level shape recorded here.",
            "Synthetic API-error assistant messages have isApiErrorMessage=true, error=<class>, and a non-msg_ message.id."
          ]
        },
        {
          "type": "system / turn_duration",
          "concept": "turn-end",
          "summary": "Marks the end of a turn with its wall time and message count.",
          "when": "When the main loop finishes a turn.",
          "fields": [
            {
              "name": "durationMs",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "messageCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "pendingBackgroundAgentCount",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"turn_duration\",\"durationMs\":42000,\"messageCount\":12,\"isMeta\":false}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / stop_hook_summary",
          "concept": "hook",
          "summary": "Summary of Stop/SubagentStop hooks run at the end of a turn.",
          "when": "After Stop hooks execute.",
          "fields": [
            {
              "name": "hasOutput",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "hookAdditionalContext",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "hookCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "hookErrors",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "hookInfos",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "hookInfos[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "hookInfos[].command",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "hookInfos[].durationMs",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "level",
              "type": "string",
              "required": true,
              "description": "Values include: suggestion."
            },
            {
              "name": "preventedContinuation",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "stopReason",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            },
            {
              "name": "toolUseID",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"stop_hook_summary\",\"hookCount\":1,\"hookInfos\":[{\"command\":\"echo ok\",\"durationMs\":12}],\"hookErrors\":[],\"preventedContinuation\":false,\"stopReason\":\"\",\"hasOutput\":false,\"level\":\"suggestion\",\"toolUseID\":\"55555555-5555-4555-8555-555555555555\"}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / away_summary",
          "concept": "summary",
          "summary": "A recap ('while you were away') summarising recent work, shown when the user returns.",
          "when": "After idle periods / background completion.",
          "fields": [
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"away_summary\",\"content\":\"Example notice\",\"isMeta\":false,\"level\":\"info\"}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / compact_boundary",
          "concept": "compaction",
          "summary": "Compaction marker: everything before it is replaced by the following isCompactSummary user entry for model context.",
          "when": "On /compact or auto-compact.",
          "fields": [
            {
              "name": "compactMetadata",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.cumulativeDroppedTokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.durationMs",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.postTokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preCompactArtifactReadVersions",
              "type": "array",
              "required": false,
              "description": "—",
              "since": "2.1.296"
            },
            {
              "name": "compactMetadata.preCompactDiscoveredTools",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "compactMetadata.preTokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedMessages",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedMessages.allUuids",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedMessages.anchorUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedMessages.uuids",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedSegment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedSegment.anchorUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedSegment.headUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.preservedSegment.tailUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "compactMetadata.trigger",
              "type": "string",
              "required": true,
              "description": "Values include: auto, manual."
            },
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "level",
              "type": "string",
              "required": true,
              "description": "Values include: info."
            },
            {
              "name": "logicalParentUuid",
              "type": "string",
              "required": true,
              "description": "On compact_boundary: the uuid of the last pre-compaction node, preserving logical continuity while parentUuid is null."
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            }
          ],
          "example": "{\"parentUuid\":null,\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"compact_boundary\",\"logicalParentUuid\":\"99999999-9999-4999-8999-999999999999\",\"content\":\"Conversation compacted\",\"level\":\"info\",\"compactMetadata\":{\"trigger\":\"auto\",\"preTokens\":180000,\"postTokens\":22000,\"durationMs\":30000}}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / local_command",
          "concept": "system-message",
          "summary": "Output/record of a local slash command (e.g. /model, /cost).",
          "when": "When a local command runs.",
          "fields": [
            {
              "name": "commandRun",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "commandRun.args",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "commandRun.command",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "level",
              "type": "string",
              "required": true,
              "description": "Values include: info."
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"local_command\",\"content\":\"Example notice\",\"isMeta\":false,\"level\":\"info\"}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / informational",
          "concept": "system-message",
          "summary": "Informational notice line shown in the transcript.",
          "when": "On notices (e.g. instruction file not loaded).",
          "fields": [
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "level",
              "type": "string",
              "required": true,
              "description": "Values include: notice."
            },
            {
              "name": "subtype",
              "type": "string",
              "required": true,
              "description": "System-record sub-discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"informational\",\"content\":\"Example notice\",\"isMeta\":false,\"level\":\"info\"}",
          "notes": [
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "system / api_error",
          "concept": "error",
          "summary": "System transcript message subtype 'api_error'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"api_error\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / microcompact_boundary",
          "concept": "compaction",
          "summary": "System transcript message subtype 'microcompact_boundary'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"microcompact_boundary\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / permission_retry",
          "concept": "permission",
          "summary": "System transcript message subtype 'permission_retry'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"permission_retry\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / memory_saved",
          "concept": "system-message",
          "summary": "System transcript message subtype 'memory_saved'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"memory_saved\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / agents_killed",
          "concept": "session-lineage",
          "summary": "System transcript message subtype 'agents_killed'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"agents_killed\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / thinking",
          "concept": "reasoning",
          "summary": "System transcript message subtype 'thinking'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"thinking\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / file_snapshot",
          "concept": "workspace-state",
          "summary": "System transcript message subtype 'file_snapshot'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"file_snapshot\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / bridge_status",
          "concept": "system-message",
          "summary": "System transcript message subtype 'bridge_status'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"bridge_status\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / scheduled_task_fire",
          "concept": "system-message",
          "summary": "System transcript message subtype 'scheduled_task_fire'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"scheduled_task_fire\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / read_divider",
          "concept": "system-message",
          "summary": "System transcript message subtype 'read_divider'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"read_divider\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / model_fallback",
          "concept": "system-message",
          "summary": "System transcript message subtype 'model_fallback'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"model_fallback\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / model_consent_fallback",
          "concept": "system-message",
          "summary": "System transcript message subtype 'model_consent_fallback'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"model_consent_fallback\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / model_refusal_fallback",
          "concept": "system-message",
          "summary": "System transcript message subtype 'model_refusal_fallback'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"model_refusal_fallback\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / model_refusal_no_fallback",
          "concept": "system-message",
          "summary": "System transcript message subtype 'model_refusal_no_fallback'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"model_refusal_no_fallback\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / rewind_stand_in",
          "concept": "compaction",
          "summary": "System transcript message subtype 'rewind_stand_in'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"rewind_stand_in\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "system / cloud_session_status",
          "concept": "system-message",
          "summary": "System transcript message subtype 'cloud_session_status'.",
          "persisted": "only system messages with persist:false are dropped by the persistence filter aE()",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"system\",\"subtype\":\"cloud_session_status\",\"content\":\"...\",\"level\":\"info\",\"isMeta\":false}",
          "notes": [
            "Field set not established beyond the common system envelope (content, level, isMeta, uuid, parentUuid...)."
          ]
        },
        {
          "type": "attachment / agent_listing_delta",
          "concept": "session-settings",
          "summary": "Delta of available subagent types announced to the model.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedLines",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedTypes",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.builtInPluginTypes",
              "type": "array",
              "required": false,
              "description": "—",
              "since": "2.1.304"
            },
            {
              "name": "attachment.builtInTypes",
              "type": "array",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "attachment.isInitial",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.removedTypes",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.showConcurrencyNote",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"agent_listing_delta\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / auto_mode",
          "concept": "permission",
          "summary": "Auto-mode (classifier permission mode) reminder/configuration.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.autoModeConsentFlow",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.bashFirst",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.bashFirstSteer",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.bypass",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.finishExposedWork",
              "type": "boolean",
              "required": false,
              "description": "—",
              "since": "2.1.307"
            },
            {
              "name": "attachment.steerOnly",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"auto_mode\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / command_permissions",
          "concept": "permission",
          "summary": "Tools allowed by a slash command (allowedTools).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.allowedTools",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"command_permissions\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / compact_file_reference",
          "concept": "compaction",
          "summary": "Reference to a file that was read before compaction (re-read hint).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.displayPath",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.filename",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.296"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"compact_file_reference\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / credential_org",
          "concept": "session-settings",
          "summary": "Organization id of the credential in use.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.organizationUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"credential_org\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / date",
          "concept": "system-message",
          "summary": "Today's date injected into context.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.date",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"date\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / deferred_tools_delta",
          "concept": "session-settings",
          "summary": "Delta of deferred (search-loaded) tools, MCP failures and surfaced definitions.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedLines",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.failedMcpServers",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.failedMcpServers[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.pendingMcpServers",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.readdedNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.removedNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.surfacedDefinitions",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.surfacedDefinitions[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.surfacedNames",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "attachment.wireHiddenNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"deferred_tools_delta\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / deferred_tools_record",
          "concept": "session-settings",
          "summary": "Record of deferred tool definitions loaded and verbatim tool-input copies.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.entries",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.entries[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.nameOnlyAnnouncements",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.toolInputCopies",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.toolInputCopies[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"deferred_tools_record\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / edited_text_file",
          "concept": "attachment",
          "summary": "Notice that a file the model read was edited externally, with a snippet.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.filename",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snippet",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"edited_text_file\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / environment",
          "concept": "session-settings",
          "summary": "Environment snapshot (platform, shell, OS, working dir, git/worktree flags) and changes.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.changes",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.changes[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.snapshot",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.additionalWorkingDirectories",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.isGitRepo",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.isWorktree",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.osVersion",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.platform",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.scratchpadDirectory",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.shell",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.snapshot.workingDirectory",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"environment\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / file",
          "concept": "attachment",
          "summary": "@-mentioned file content attached to a prompt.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.file",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator. Values include: text."
            },
            {
              "name": "attachment.displayPath",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.filename",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.296"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"file\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / hook_additional_context",
          "concept": "hook",
          "summary": "additionalContext returned by a hook (e.g. SessionStart).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.hookEvent",
              "type": "string",
              "required": true,
              "description": "Values include: SessionStart."
            },
            {
              "name": "attachment.hookName",
              "type": "string",
              "required": true,
              "description": "Values include: SessionStart."
            },
            {
              "name": "attachment.toolUseID",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_additional_context\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / hook_success",
          "concept": "hook",
          "summary": "A hook ran successfully; command, exit code, stdout/stderr, duration.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "persisted": "only dropped when content, stdout and stderr are all empty",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.command",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.durationMs",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.exitCode",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.hookEvent",
              "type": "string",
              "required": true,
              "description": "Values include: SessionStart."
            },
            {
              "name": "attachment.hookName",
              "type": "string",
              "required": true,
              "description": "Values include: SessionStart:startup, SessionStart:clear, SessionStart:compact, SessionStart:resume."
            },
            {
              "name": "attachment.stderr",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.stdout",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.toolUseID",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_success\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / instructions",
          "concept": "system-message",
          "summary": "CLAUDE.md / memory instruction files loaded (path, type User|Project|AutoMem, content).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.changed",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.files",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.files[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.reason",
              "type": "string",
              "required": false,
              "description": "Values include: compaction, session_start."
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"instructions\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / invoked_skills",
          "concept": "attachment",
          "summary": "Skills invoked so far (re-attached after compaction).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.skills",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.skills[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.296"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"invoked_skills\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / mcp_instructions_delta",
          "concept": "system-message",
          "summary": "Delta of MCP server instructions blocks.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedBlocks",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.addedNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.removedNames",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"mcp_instructions_delta\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / model",
          "concept": "session-settings",
          "summary": "Model identity (modelId, marketingName, knowledgeCutoff).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.identity",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.identity.knowledgeCutoff",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.identity.marketingName",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.identity.modelId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"model\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / nested_memory",
          "concept": "system-message",
          "summary": "Nested CLAUDE.md discovered under a directory touched by a tool.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.contentDiffersFromDisk",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.path",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator. Values include: Project."
            },
            {
              "name": "attachment.displayPath",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.path",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"nested_memory\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / prompt_snapshot",
          "concept": "session-settings",
          "summary": "Snapshot of the system prompt sections and tool list in force.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.cliPrefix",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.contextRendering",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.echoWireToolInputs",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.inlineTools",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.keptReminders",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.reminderFold",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.systemPrompt",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.systemTurns",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.toolChangeHeader",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.tools",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.tools[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"prompt_snapshot\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / queued_command",
          "concept": "queue",
          "summary": "A queued prompt or task notification delivered mid-turn.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.commandMode",
              "type": "string",
              "required": false,
              "description": "Values include: task-notification, prompt."
            },
            {
              "name": "attachment.delivery_id",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.287"
            },
            {
              "name": "attachment.humanTurn",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.isMeta",
              "type": "boolean",
              "required": false,
              "description": "true for system-injected entries not typed by the user (caveats, reminders, hook output, notices)."
            },
            {
              "name": "attachment.origin",
              "type": "object",
              "required": false,
              "description": "Provenance of a non-typed or queued prompt: {kind, name?, from?, body?, producer?, runId?, senderTaskId?, handback?, handbackReportText?}."
            },
            {
              "name": "attachment.origin.body",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.origin.from",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.origin.handback",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.origin.handbackReportText",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.300"
            },
            {
              "name": "attachment.origin.kind",
              "type": "string",
              "required": false,
              "description": "Values include: task-notification, human, peer, coordinator."
            },
            {
              "name": "attachment.origin.name",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.288"
            },
            {
              "name": "attachment.origin.producer",
              "type": "string",
              "required": false,
              "description": "Values include: session-task."
            },
            {
              "name": "attachment.origin.senderTaskId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.prompt",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.reminderId",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.288"
            },
            {
              "name": "attachment.runId",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.293"
            },
            {
              "name": "attachment.source_uuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.timestamp",
              "type": "string",
              "required": false,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "attachment.usage",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.usage.durationMs",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.usage.toolUses",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.usage.totalTokens",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedInHumanTurn",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "renderedInHumanTurn[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "renderedInHumanTurn[].content",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.287"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"queued_command\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / read_truncation_notice",
          "concept": "tool-result",
          "summary": "Notice that a Read result was truncated.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.banner",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.toolUseID",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.295"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"read_truncation_notice\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / session_context",
          "concept": "system-message",
          "summary": "Session context (user email, git status) injected at start.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.context",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.context.gitStatus",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "attachment.context.userEmail",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"session_context\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / silent_turn_reminder",
          "concept": "system-message",
          "summary": "Reminder injected after several silent tool-only turns.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"silent_turn_reminder\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / skill_listing",
          "concept": "session-settings",
          "summary": "Listing of available skills (names, digests).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.digests",
              "type": "array",
              "required": false,
              "description": "—",
              "since": "2.1.304"
            },
            {
              "name": "attachment.isInitial",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.names",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.skillCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"skill_listing\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / task_status",
          "concept": "tool-progress",
          "summary": "Status of a background task/monitor.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.deltaSummary",
              "type": "null",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.description",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.outputFilePath",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.shell",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.shell.command",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.shell.kind",
              "type": "string",
              "required": true,
              "description": "Values include: monitor."
            },
            {
              "name": "attachment.shell.toolUseId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.status",
              "type": "string",
              "required": true,
              "description": "Values include: running."
            },
            {
              "name": "attachment.taskId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.taskType",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"task_status\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / thinking_drop",
          "concept": "reasoning",
          "summary": "Diagnostic: thinking blocks dropped from the request due to prefix mismatch.",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.blockHashes",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.clientChange",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.clientChange.baseline",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.clientChange.callNumber",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.clientChange.firstChangedMessageIndex",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.clientChange.kinds",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.firstReportForThreadInProcess",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.model",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped.blockCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped.first",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped.last",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped.reason",
              "type": "string",
              "required": true,
              "description": "Values include: prefix_mismatch."
            },
            {
              "name": "attachment.newlyDropped.reasonCounts",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.newlyDropped.turnCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.querySource",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.requestId",
              "type": "string",
              "required": true,
              "description": "Anthropic API request id ('req_...') of the response this assistant line came from."
            },
            {
              "name": "attachment.thinkingBlocksSent",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.thinkingTurnsSent",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"thinking_drop\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / total_tokens_reminder",
          "concept": "token-usage",
          "summary": "Context-budget reminder (tokens left).",
          "when": "Collected before a model request (or by the triggering event) and persisted as its own line.",
          "fields": [
            {
              "name": "attachment",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "attachment.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator."
            },
            {
              "name": "rendered",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "renderedRole",
              "type": "string",
              "required": false,
              "description": "—",
              "since": "2.1.285"
            },
            {
              "name": "rendered[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "rendered[].content",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"total_tokens_reminder\"}}",
          "notes": [
            "rendered[] holds the text actually sent to the model; renderedRole is its role.",
            "Also carries the conversation envelope (see top-level envelope): uuid, parentUuid, isSidechain, sessionId, timestamp, version, cwd, gitBranch, userType, entrypoint, slug?, agentId? (subagent files), session_id? (some lines)."
          ]
        },
        {
          "type": "attachment / account_memory_recall",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"account_memory_recall\"}}"
        },
        {
          "type": "attachment / advisor_stripped",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"advisor_stripped\"}}"
        },
        {
          "type": "attachment / advisor_tool",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"advisor_tool\"}}"
        },
        {
          "type": "attachment / agent_mention",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"agent_mention\"}}"
        },
        {
          "type": "attachment / already_read_file",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"already_read_file\"}}"
        },
        {
          "type": "attachment / artifact_opening_prefetch",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"artifact_opening_prefetch\"}}"
        },
        {
          "type": "attachment / async_hook_response",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"async_hook_response\"}}"
        },
        {
          "type": "attachment / async_hook_response_batch",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"async_hook_response_batch\"}}"
        },
        {
          "type": "attachment / at_mention_reference",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"at_mention_reference\"}}"
        },
        {
          "type": "attachment / attention_budget",
          "concept": "token-usage",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"attention_budget\"}}"
        },
        {
          "type": "attachment / auto_mode_exit",
          "concept": "permission",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"auto_mode_exit\"}}"
        },
        {
          "type": "attachment / bash_output_audience_note",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"bash_output_audience_note\"}}"
        },
        {
          "type": "attachment / batching_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"batching_reminder\"}}"
        },
        {
          "type": "attachment / batching_reminder_sent",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"batching_reminder_sent\"}}"
        },
        {
          "type": "attachment / budget_usd",
          "concept": "token-usage",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"budget_usd\"}}"
        },
        {
          "type": "attachment / context_efficiency",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"context_efficiency\"}}"
        },
        {
          "type": "attachment / context_sections",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"context_sections\"}}"
        },
        {
          "type": "attachment / coordinator_context",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"coordinator_context\"}}"
        },
        {
          "type": "attachment / cowork_memory_context",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"cowork_memory_context\"}}"
        },
        {
          "type": "attachment / critical_system_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"critical_system_reminder\"}}"
        },
        {
          "type": "attachment / date_change",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"date_change\"}}"
        },
        {
          "type": "attachment / diagnostics",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"diagnostics\"}}"
        },
        {
          "type": "attachment / directory",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"directory\"}}"
        },
        {
          "type": "attachment / dir_sync_notice",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"dir_sync_notice\"}}"
        },
        {
          "type": "attachment / dynamic_skill",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"dynamic_skill\"}}"
        },
        {
          "type": "attachment / edited_image_file",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"edited_image_file\"}}"
        },
        {
          "type": "attachment / elapsed_time_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"elapsed_time_reminder\"}}"
        },
        {
          "type": "attachment / fork_briefing",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"fork_briefing\"}}"
        },
        {
          "type": "attachment / goal_status",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"goal_status\"}}"
        },
        {
          "type": "attachment / goals",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"goals\"}}"
        },
        {
          "type": "attachment / hook_blocking_error",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_blocking_error\"}}"
        },
        {
          "type": "attachment / hook_cancelled",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_cancelled\"}}"
        },
        {
          "type": "attachment / hook_deferred_tool",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_deferred_tool\"}}"
        },
        {
          "type": "attachment / hook_error_during_execution",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_error_during_execution\"}}"
        },
        {
          "type": "attachment / hook_non_blocking_error",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_non_blocking_error\"}}"
        },
        {
          "type": "attachment / hook_permission_decision",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_permission_decision\"}}"
        },
        {
          "type": "attachment / hook_plugin_listing",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_plugin_listing\"}}"
        },
        {
          "type": "attachment / hook_stopped_continuation",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_stopped_continuation\"}}"
        },
        {
          "type": "attachment / hook_system_message",
          "concept": "hook",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"hook_system_message\"}}"
        },
        {
          "type": "attachment / inlined_image_paths",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"inlined_image_paths\"}}"
        },
        {
          "type": "attachment / language",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"language\"}}"
        },
        {
          "type": "attachment / max_turns_reached",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"max_turns_reached\"}}"
        },
        {
          "type": "attachment / mcp_dropped_tools_delta",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"mcp_dropped_tools_delta\"}}"
        },
        {
          "type": "attachment / mcp_resource",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"mcp_resource\"}}"
        },
        {
          "type": "attachment / memory_update",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"memory_update\"}}"
        },
        {
          "type": "attachment / opened_file_in_ide",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"opened_file_in_ide\"}}"
        },
        {
          "type": "attachment / output_limit_note",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"output_limit_note\"}}"
        },
        {
          "type": "attachment / output_style",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"output_style\"}}"
        },
        {
          "type": "attachment / output_style_instructions",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"output_style_instructions\"}}"
        },
        {
          "type": "attachment / output_token_usage",
          "concept": "token-usage",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"output_token_usage\"}}"
        },
        {
          "type": "attachment / pdf_reference",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"pdf_reference\"}}"
        },
        {
          "type": "attachment / peer_mention",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"peer_mention\"}}"
        },
        {
          "type": "attachment / plan_file_reference",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"plan_file_reference\"}}"
        },
        {
          "type": "attachment / plan_mode",
          "concept": "permission",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"plan_mode\"}}"
        },
        {
          "type": "attachment / plan_mode_exit",
          "concept": "permission",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"plan_mode_exit\"}}"
        },
        {
          "type": "attachment / plan_mode_reentry",
          "concept": "permission",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"plan_mode_reentry\"}}"
        },
        {
          "type": "attachment / poll_events",
          "concept": "queue",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"poll_events\"}}"
        },
        {
          "type": "attachment / prefix_delta",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"prefix_delta\"}}"
        },
        {
          "type": "attachment / proactivity",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"proactivity\"}}"
        },
        {
          "type": "attachment / project_doc_reads",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"project_doc_reads\"}}"
        },
        {
          "type": "attachment / projects_thread_ask",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"projects_thread_ask\"}}"
        },
        {
          "type": "attachment / prompt_render_point",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"prompt_render_point\"}}"
        },
        {
          "type": "attachment / relevant_memories",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"relevant_memories\"}}"
        },
        {
          "type": "attachment / remote_session_change",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"remote_session_change\"}}"
        },
        {
          "type": "attachment / sandbox_instructions",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"sandbox_instructions\"}}"
        },
        {
          "type": "attachment / secondary_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"secondary_reminder\"}}"
        },
        {
          "type": "attachment / secondary_reminder_sent",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"secondary_reminder_sent\"}}"
        },
        {
          "type": "attachment / selected_lines_in_diff",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"selected_lines_in_diff\"}}"
        },
        {
          "type": "attachment / selected_lines_in_ide",
          "concept": "attachment",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"selected_lines_in_ide\"}}"
        },
        {
          "type": "attachment / session_cron_carry",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"session_cron_carry\"}}"
        },
        {
          "type": "attachment / session_settings",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"session_settings\"}}"
        },
        {
          "type": "attachment / skill_mention",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"skill_mention\"}}"
        },
        {
          "type": "attachment / structured_output",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"structured_output\"}}"
        },
        {
          "type": "attachment / task_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"task_reminder\"}}"
        },
        {
          "type": "attachment / team_context",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"team_context\"}}"
        },
        {
          "type": "attachment / teammate_mailbox",
          "concept": "queue",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"teammate_mailbox\"}}"
        },
        {
          "type": "attachment / teammate_shutdown_batch",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"teammate_shutdown_batch\"}}"
        },
        {
          "type": "attachment / thinking_stripped",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"thinking_stripped\"}}"
        },
        {
          "type": "attachment / thread_state",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"thread_state\"}}"
        },
        {
          "type": "attachment / todo_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"todo_reminder\"}}"
        },
        {
          "type": "attachment / token_usage",
          "concept": "token-usage",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"token_usage\"}}"
        },
        {
          "type": "attachment / tool_host_result_lines",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"tool_host_result_lines\"}}"
        },
        {
          "type": "attachment / tool_hosts_correction",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"tool_hosts_correction\"}}"
        },
        {
          "type": "attachment / tool_hosts_notice",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"tool_hosts_notice\"}}"
        },
        {
          "type": "attachment / tool_search_usage_reminder",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"tool_search_usage_reminder\"}}"
        },
        {
          "type": "attachment / ultra_effort_enter",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"ultra_effort_enter\"}}"
        },
        {
          "type": "attachment / ultra_effort_exit",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"ultra_effort_exit\"}}"
        },
        {
          "type": "attachment / ultrathink_effort",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"ultrathink_effort\"}}"
        },
        {
          "type": "attachment / unknown_command_fallback",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"unknown_command_fallback\"}}"
        },
        {
          "type": "attachment / withheld_memory",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"withheld_memory\"}}"
        },
        {
          "type": "attachment / workflow_keyword_request",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"workflow_keyword_request\"}}"
        },
        {
          "type": "attachment / workflow_size_guideline_change",
          "concept": "system-message",
          "summary": "Its fields are not established for this version.",
          "persisted": "only subject to persistence filter aE(); some types are rendered-only or ant-only",
          "fields": [],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"attachment\",\"attachment\":{\"type\":\"workflow_size_guideline_change\"}}"
        },
        {
          "type": "progress",
          "concept": "tool-progress",
          "summary": "Legacy streaming progress line for a running tool/hook/agent (data.type bash_progress, mcp_progress, agent_progress, hook_progress, tool_heartbeat, ...).",
          "when": "Historically written while tools ran. In 2.1.310 the persistence filter aE() returns false for every progress entry, so new files do not contain them.",
          "until": "not written by 2.1.310 (exact removal version not established)",
          "persisted": "never-on-disk (2.1.310: filtered at write); legacy files may contain them",
          "fields": [
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "Progress payload discriminated by data.type."
            },
            {
              "name": "toolUseID",
              "type": "string",
              "required": false,
              "description": "tool_use id the progress belongs to."
            },
            {
              "name": "parentToolUseID",
              "type": "string",
              "required": false,
              "description": "Parent tool_use id (for nested agent progress)."
            }
          ],
          "example": "{\"parentUuid\":\"11111111-1111-4111-8111-111111111111\",\"isSidechain\":false,\"userType\":\"external\",\"cwd\":\"/home/user/project\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"version\":\"2.1.310\",\"gitBranch\":\"main\",\"entrypoint\":\"cli\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"uuid\":\"22222222-2222-4222-8222-222222222222\",\"type\":\"progress\",\"toolUseID\":\"toolu_01Example\",\"parentToolUseID\":\"toolu_01Example\",\"data\":{\"type\":\"bash_progress\",\"output\":\"...\",\"elapsedTimeSeconds\":3}}",
          "notes": [
            "Loader still reads legacy progress lines: it records their parentUuid and re-parents any child whose parentUuid points at a progress uuid onto the progress line's own parent (progress lines are skipped, not kept in the chain).",
            "Known data.type values: bash_progress, powershell_progress, mcp_progress, tool_heartbeat, agent_api_retry, artifact_publish_retry, agent_progress, hook_progress, skill_progress, search_results_received, workflow_agent, workflow_log."
          ]
        },
        {
          "type": "ai-title",
          "concept": "session-title",
          "summary": "AI-generated session title.",
          "when": "When a title is generated; re-appended to the file tail repeatedly (see gotchas).",
          "fields": [
            {
              "name": "aiTitle",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"ai-title\",\"aiTitle\":\"Setup docs update\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}",
          "notes": ["No timestamp/version/uuid. Repeated many times per file. Last one wins."]
        },
        {
          "type": "last-prompt",
          "concept": "session-lineage",
          "summary": "Leaf pointer: which node is the current conversation tip (leafUuid) and the last prompt text.",
          "when": "After each turn and on rewind; re-appended to the tail.",
          "fields": [
            {
              "name": "explicit",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "lastPrompt",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "leafUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"last-prompt\",\"lastPrompt\":\"Add a README section\",\"leafUuid\":\"44444444-4444-4444-8444-444444444444\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}",
          "notes": [
            "explicit:true marks a user-chosen leaf (e.g. /rewind); rewound:true marks a rewind; leafUuid:null + explicit:true withdraws the leaf (fresh start after /clear-style reset)."
          ]
        },
        {
          "type": "mode",
          "concept": "session-settings",
          "summary": "Session mode (normal / other UI modes). Last wins.",
          "when": "Re-appended with session metadata.",
          "fields": [
            {
              "name": "mode",
              "type": "string",
              "required": true,
              "description": "Values include: normal."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"mode\",\"mode\":\"normal\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "permission-mode",
          "concept": "session-settings",
          "summary": "Current permission mode. Last wins.",
          "when": "When the mode changes; re-appended with metadata.",
          "fields": [
            {
              "name": "permissionMode",
              "type": "string",
              "required": true,
              "description": "Permission mode in force when the prompt was submitted (default/acceptEdits/plan/auto/bypassPermissions...). Values include: auto."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"permission-mode\",\"permissionMode\":\"default\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "atis-latch",
          "concept": "metadata-other",
          "summary": "Opaque printable-ASCII latch value for the session (internal feature latch).",
          "when": "Re-appended with metadata.",
          "fields": [
            {
              "name": "atis",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"atis-latch\",\"atis\":\"x1\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}",
          "notes": ["Loader accepts only /^[\\x21-\\x7e]*$/ values."]
        },
        {
          "type": "cost-state",
          "concept": "cost",
          "summary": "Cumulative session cost and per-model token totals; restores /cost on resume.",
          "when": "Periodically and on exit.",
          "fields": [
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session id."
            },
            {
              "name": "totalCostUSD",
              "type": "number",
              "required": true,
              "description": "Estimated cumulative USD cost."
            },
            {
              "name": "totalAPIDuration",
              "type": "number",
              "required": true,
              "description": "ms spent in API calls incl. retries."
            },
            {
              "name": "totalAPIDurationWithoutRetries",
              "type": "number",
              "required": true,
              "description": "ms in API calls excluding retries."
            },
            {
              "name": "totalToolDuration",
              "type": "number",
              "required": true,
              "description": "ms spent executing tools."
            },
            {
              "name": "totalLinesAdded",
              "type": "number",
              "required": true,
              "description": "Lines added by edits."
            },
            {
              "name": "totalLinesRemoved",
              "type": "number",
              "required": true,
              "description": "Lines removed."
            },
            {
              "name": "totalDuration",
              "type": "number",
              "required": true,
              "description": "Session wall ms."
            },
            {
              "name": "startTime",
              "type": "number",
              "required": true,
              "description": "Epoch ms of session start."
            },
            {
              "name": "modelUsage.<model>",
              "type": "object",
              "required": true,
              "description": "{inputTokens, outputTokens, thinkingTokens?, cacheReadInputTokens, cacheCreationInputTokens, webSearchRequests, costUSD} per model id."
            },
            {
              "name": "hasUnknownModelCost",
              "type": "boolean",
              "required": false,
              "description": "A model without a price table was used."
            }
          ],
          "example": "{\"type\":\"cost-state\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"totalCostUSD\":1.23,\"totalAPIDuration\":60000,\"totalAPIDurationWithoutRetries\":59000,\"totalToolDuration\":20000,\"totalLinesAdded\":10,\"totalLinesRemoved\":2,\"totalDuration\":300000,\"startTime\":1760000000000,\"modelUsage\":{\"claude-opus-5-5\":{\"inputTokens\":100,\"outputTokens\":50,\"thinkingTokens\":10,\"cacheReadInputTokens\":9000,\"cacheCreationInputTokens\":500,\"webSearchRequests\":0,\"costUSD\":1.23}},\"hasUnknownModelCost\":false}",
          "notes": [
            "modelUsage is keyed by model id (dynamic keys). Zod-validated on load (Wnn): numbers nonnegative/finite; totalCostUSD <= 1e9."
          ]
        },
        {
          "type": "pr-link",
          "concept": "session-lineage",
          "summary": "Links the session to a pull request.",
          "when": "When Claude Code detects/creates a PR for the session.",
          "fields": [
            {
              "name": "prNumber",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "prRepository",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "prUrl",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            }
          ],
          "example": "{\"type\":\"pr-link\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"prNumber\":42,\"prUrl\":\"https://github.com/example/repo/pull/42\",\"prRepository\":\"example/repo\",\"timestamp\":\"2026-10-20T10:00:00.000Z\"}"
        },
        {
          "type": "queue-operation",
          "concept": "queue",
          "summary": "Prompt-queue journal: a prompt was enqueued, dequeued or removed while Claude was busy.",
          "when": "On queue changes.",
          "fields": [
            {
              "name": "commandUuid",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "content",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "deliveryId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "operation",
              "type": "string",
              "required": true,
              "description": "Values include: enqueue, dequeue, remove."
            },
            {
              "name": "reason",
              "type": "string",
              "required": false,
              "description": "Values include: absorbed_mid_turn, delivered_to_agent."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            }
          ],
          "example": "{\"type\":\"queue-operation\",\"operation\":\"enqueue\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"content\":\"also update the tests\"}",
          "notes": [
            "operation ∈ enqueue|dequeue|remove; Claude Code also passes popAll/clear-style ops through the same writer. content is the queued prompt text."
          ]
        },
        {
          "type": "file-history-snapshot",
          "concept": "workspace-state",
          "summary": "Checkpoint of tracked files for /rewind, keyed to a user message.",
          "when": "At each user prompt (initial) and when tracked files change (isSnapshotUpdate:true).",
          "fields": [
            {
              "name": "isSnapshotUpdate",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "messageId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "snapshot",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "snapshot.messageId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "snapshot.timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "snapshot.trackedFileBackups",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "snapshot.trackedFileBackups.<dynamic-key>",
              "type": "object",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"file-history-snapshot\",\"messageId\":\"22222222-2222-4222-8222-222222222222\",\"snapshot\":{\"messageId\":\"22222222-2222-4222-8222-222222222222\",\"trackedFileBackups\":{\"src/app.ts\":{\"backupFileName\":\"0123456789abcdef@v2\",\"version\":2,\"backupTime\":\"2026-10-20T10:00:00.000Z\",\"realParentDir\":\"/home/user/project/src\"}},\"timestamp\":\"2026-10-20T10:00:00.000Z\"},\"isSnapshotUpdate\":false}",
          "notes": [
            "trackedFileBackups keys are file paths (dynamic). backupFileName null means the file did not exist at that version.",
            "backupFileName names a file in ~/.claude/file-history/<sessionId>/ (names match /^[0-9a-f]{16}@v\\d+$/). Names can also be a 48-hex suffix."
          ]
        },
        {
          "type": "file-history-delta",
          "concept": "workspace-state",
          "summary": "Incremental file-history backup for one tracked path, attached to an existing snapshot (smaller than re-writing the snapshot).",
          "when": "When a tracked file is backed up after the snapshot was written.",
          "fields": [
            {
              "name": "backup",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "backup.backupFileName",
              "type": "null|string",
              "required": true,
              "description": "—"
            },
            {
              "name": "backup.backupTime",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "backup.realParentDir",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "backup.version",
              "type": "number",
              "required": true,
              "description": "Claude Code version string that wrote the entry (semver)."
            },
            {
              "name": "messageId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "snapshotMessageId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "trackingPath",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"file-history-delta\",\"messageId\":\"22222222-2222-4222-8222-222222222222\",\"snapshotMessageId\":\"22222222-2222-4222-8222-222222222222\",\"trackingPath\":\"src/app.ts\",\"backup\":{\"backupFileName\":\"0123456789abcdef@v3\",\"version\":3,\"backupTime\":\"2026-10-20T10:00:00.000Z\",\"realParentDir\":\"/home/user/project/src\"},\"timestamp\":\"2026-10-20T10:00:00.000Z\"}",
          "notes": [
            "Loader groups deltas by messageId and applies them on top of the snapshot with the same messageId. Probably introduced with 2.1.208 file-history pruning (not established)."
          ]
        },
        {
          "type": "api-request",
          "concept": "metadata-other",
          "summary": "Request-replay record: parameters of one API request, with messages expressed as content-addressed blob hashes (base + keep + tail).",
          "when": "Before each main-thread or subagent API call (since 2.1.300).",
          "since": "2.1.300",
          "fields": [
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "base",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "cacheControl",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "cacheControl[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "cacheControl[].path",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "cacheControl[].value",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "keep",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "params",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.betas",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.context_management",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.context_management.edits",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.max_tokens",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.model",
              "type": "string",
              "required": true,
              "description": "Values include: claude-opus-5-5, claude-sonnet-5-5."
            },
            {
              "name": "params.output_config",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.output_config.effort",
              "type": "string",
              "required": true,
              "description": "Effort level of the request (low/medium/high/xhigh/max). Values include: medium."
            },
            {
              "name": "params.safeguards",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "params.safeguards[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "params.thinking",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "params.thinking.display",
              "type": "string",
              "required": true,
              "description": "Values include: updates."
            },
            {
              "name": "params.thinking.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator. Values include: adaptive."
            },
            {
              "name": "querySource",
              "type": "string",
              "required": true,
              "description": "Values include: repl_main_thread, agent:builtin:general-purpose, agent:builtin:Explore, agent:custom, agent:custom:<plugin-agent>."
            },
            {
              "name": "requestDigest",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "shapeHash",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "tail",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "tail[]",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "version",
              "type": "string",
              "required": true,
              "description": "Claude Code version string that wrote the entry (semver)."
            }
          ],
          "example": "{\"type\":\"api-request\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"id\":\"r_example1\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"version\":1,\"querySource\":\"repl_main_thread\",\"shapeHash\":\"ab12\",\"params\":{\"model\":\"claude-opus-5-5\",\"max_tokens\":64000,\"thinking\":{\"type\":\"adaptive\"}},\"base\":\"r_example0\",\"keep\":12,\"tail\":[\"cd34\",\"ef56\"],\"cacheControl\":[],\"requestDigest\":\"9a8b\"}",
          "notes": [
            "messages = (messages of api-request `base`)[0:keep] + tail; each hash resolves to an api-request-blob.message in the same file. `base` usually points at an earlier api-request.",
            "shapeHash resolves to an api-request-shape record (system + tools). version here is the replay-format version (number), NOT the Claude Code version.",
            "Optional: agentId (subagent requests are routed to the subagent file), withheld (param names withheld because they came from CLAUDE_CODE_EXTRA_BODY), cut + cutRequestDigest (when memory-cut messages were substituted).",
            "params.safeguards[].classifier_context (full auto-mode classifier context) appears only 2.1.300–2.1.303; 2.1.304 changelog: classifier context no longer stored with every request."
          ]
        },
        {
          "type": "api-request-blob",
          "concept": "metadata-other",
          "summary": "Content-addressed copy of one request message (system/user/assistant) referenced by api-request.tail hashes.",
          "when": "Written once per new hash, before the api-request that references it.",
          "since": "2.1.300",
          "fields": [
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "hash",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "message",
              "type": "object",
              "required": true,
              "description": "Anthropic Messages API message object (role + content + for assistant: id/model/usage/stop fields)."
            },
            {
              "name": "message.content",
              "type": "array|string",
              "required": true,
              "description": "String (plain prompt or command output) or array of content blocks; see contentBlocks."
            },
            {
              "name": "message.output_config",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.output_config.effort",
              "type": "string",
              "required": false,
              "description": "Effort level of the request (low/medium/high/xhigh/max)."
            },
            {
              "name": "message.role",
              "type": "string",
              "required": true,
              "description": "Message role. Values include: system, assistant, user."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            }
          ],
          "example": "{\"type\":\"api-request-blob\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"hash\":\"cd34\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Hello\"}]}}",
          "notes": [
            "message.role includes \"system\" (system blocks and tool_addition blocks), which is not an Anthropic API role: these are replay-internal."
          ]
        },
        {
          "type": "api-request-shape",
          "concept": "session-settings",
          "summary": "Content-addressed request shape: the system prompt blocks and tool definitions of a request.",
          "when": "Once per distinct shapeHash per file.",
          "since": "2.1.300",
          "fields": [
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "shape",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "shape.system",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "shape.system[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "shape.tools",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "shape.tools[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "shapeHash",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "version",
              "type": "string",
              "required": true,
              "description": "Claude Code version string that wrote the entry (semver)."
            }
          ],
          "example": "{\"type\":\"api-request-shape\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"shapeHash\":\"ab12\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"version\":1,\"shape\":{\"system\":[{\"type\":\"text\",\"text\":\"You are ...\"}],\"tools\":[{\"name\":\"Read\",\"description\":\"...\",\"input_schema\":{\"type\":\"object\"}}]}}",
          "notes": [
            "Shapes larger than the cap are not recorded (oversize shapes are remembered and their requests skipped)."
          ]
        },
        {
          "type": "fork-context-ref",
          "concept": "session-lineage",
          "summary": "In a forked subagent transcript: points at the parent conversation prefix the fork inherited instead of copying it.",
          "when": "At fork-subagent start.",
          "fields": [
            {
              "name": "agentId",
              "type": "string",
              "required": true,
              "description": "Subagent id (17 hex chars) on entries written by/for a subagent; matches the agent-<agentId>.jsonl filename."
            },
            {
              "name": "contextLength",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "parentLastUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "parentSessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"fork-context-ref\",\"agentId\":\"a0123456789abcdef\",\"parentSessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"parentLastUuid\":\"44444444-4444-4444-8444-444444444444\",\"contextLength\":120}",
          "notes": [
            "Values include only in subagent files. parentSessionId is the containing session."
          ]
        },
        {
          "type": "frame-link",
          "concept": "metadata-other",
          "summary": "Count/link of artifacts (frames) published from the session.",
          "when": "When an artifact is published; re-appended with metadata.",
          "fields": [
            {
              "name": "artifactCount",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "frameUrl",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "path",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "ISO-8601 UTC write time."
            },
            {
              "name": "title",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"frame-link\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"artifactCount\":1,\"timestamp\":\"2026-10-20T10:00:00.000Z\"}"
        },
        {
          "type": "artifact-comment-monitor",
          "concept": "metadata-other",
          "summary": "State of armed artifact comment watchers, keyed by artifact id.",
          "when": "When watchers change.",
          "fields": [
            {
              "name": "artifacts",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.state",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.title",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.writtenAtMs",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "v",
              "type": "number",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"artifact-comment-monitor\",\"v\":1,\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"artifacts\":{\"art_1\":{\"state\":\"armed\",\"title\":\"Example\",\"writtenAtMs\":1760000000000}}}"
        },
        {
          "type": "artifact-autoreact-ledger",
          "concept": "metadata-other",
          "summary": "Ledger of artifact comment threads already reacted to, per artifact.",
          "when": "When the auto-react ledger changes.",
          "fields": [
            {
              "name": "accountUuid",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.everBaselined",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.everHadThreads",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.savedAt",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.stampHighWater",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.threads",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "artifacts.<dynamic-key>.turnTimestamps",
              "type": "array",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "Session UUID. Equals the transcript filename stem in main files; in subagent files it is the PARENT session id."
            },
            {
              "name": "v",
              "type": "number",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"artifact-autoreact-ledger\",\"v\":1,\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"accountUuid\":\"00000000-0000-4000-8000-000000000000\",\"artifacts\":{}}"
        },
        {
          "type": "summary",
          "concept": "summary",
          "summary": "Legacy conversation summary keyed to a leaf (pre-compact_boundary era). Loader still maps leafUuid -> summary.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "summary",
              "type": "string",
              "required": true,
              "description": "Summary text."
            },
            {
              "name": "leafUuid",
              "type": "string",
              "required": true,
              "description": "Leaf node the summary describes."
            }
          ],
          "example": "{\"type\":\"summary\",\"summary\":\"Setup docs work\",\"leafUuid\":\"44444444-4444-4444-8444-444444444444\"}"
        },
        {
          "type": "custom-title",
          "concept": "session-title",
          "summary": "User-set session title (/rename, --name, hook sessionTitle). Takes precedence over ai-title.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "customTitle",
              "type": "string",
              "required": true,
              "description": "Title; empty string clears."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"custom-title\",\"customTitle\":\"Docs work\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "tag",
          "concept": "metadata-other",
          "summary": "Session tag.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "tag",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tag\",\"tag\":\"docs\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "agent-name",
          "concept": "session-title",
          "summary": "Name of the session when run as a named agent/teammate.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "agentName",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"agent-name\",\"agentName\":\"reviewer\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "agent-color",
          "concept": "metadata-other",
          "summary": "Display color for a named agent.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "agentColor",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"agent-color\",\"agentColor\":\"blue\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "agent-setting",
          "concept": "session-settings",
          "summary": "Agent definition/setting the session runs under (--agent).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "agentSetting",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"agent-setting\",\"agentSetting\":\"reviewer\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "relocated",
          "concept": "session-lineage",
          "summary": "The session transcript was relocated to another cwd/project directory (/cd).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "relocatedCwd",
              "type": "string",
              "required": true,
              "description": "New working directory."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"relocated\",\"relocatedCwd\":\"/home/user/other\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "ended-by-model",
          "concept": "turn-end",
          "summary": "The model ended the session (end-session tool).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"ended-by-model\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "continued-in",
          "concept": "session-lineage",
          "summary": "Forward pointer: this session continues in another session id.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "continuedInSessionId",
              "type": "string",
              "required": true,
              "description": "Successor session id."
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"continued-in\",\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"continuedInSessionId\":\"bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb\"}"
        },
        {
          "type": "worktree-state",
          "concept": "workspace-state",
          "summary": "Git worktree the session runs in (EnterWorktree/--worktree).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "worktreeSession",
              "type": "object|null",
              "required": true,
              "description": "Worktree session descriptor (path/branch...); shape not established."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"worktree-state\",\"worktreeSession\":{\"worktreePath\":\"/home/user/project/.claude/worktrees/x\",\"worktreeBranch\":\"x\"},\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "isolation-latch",
          "concept": "session-settings",
          "summary": "Which side of an isolation boundary the session is latched to.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "side",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"isolation-latch\",\"side\":\"local\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "dev-mods",
          "concept": "session-settings",
          "summary": "Folder of development mods loaded for the session (validated to belong to the session).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "folder",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"dev-mods\",\"folder\":\"/home/user/.claude/mods/dev\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "memory-mode",
          "concept": "session-settings",
          "summary": "Memory on/off stamp positioned after a message uuid.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "mode",
              "type": "enum(on,off)",
              "required": true,
              "description": "—"
            },
            {
              "name": "afterUuid",
              "type": "string|null",
              "required": true,
              "description": "Node after which the mode applies."
            },
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "reason",
              "type": "enum(paused,account_off,account_read_only,session_shape,server_off)",
              "required": false,
              "description": "—"
            },
            {
              "name": "account",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "accountChoice",
              "type": "enum(on,read_only,off)",
              "required": false,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"memory-mode\",\"mode\":\"off\",\"afterUuid\":null,\"timestamp\":\"2026-10-20T10:00:00.000Z\",\"reason\":\"paused\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\"}"
        },
        {
          "type": "bridge-session",
          "concept": "session-lineage",
          "summary": "Remote Control / bridge binding of the local session to a remote session id.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "bridgeSessionId",
              "type": "string",
              "required": true,
              "description": "Remote session id ('' clears)."
            },
            {
              "name": "lastSequenceNum",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "declaredDialogKinds",
              "type": "array",
              "required": false,
              "description": "—"
            },
            {
              "name": "sessionGroupingId",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "noHistoryBackfill",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "ownerAccountUuid",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "ownerOrganizationUuid",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"bridge-session\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"bridgeSessionId\":\"session_example\",\"lastSequenceNum\":0}"
        },
        {
          "type": "history-suppression",
          "concept": "metadata-other",
          "summary": "Marks the session as suppressed from prompt history / listing.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "cause",
              "type": "string",
              "required": true,
              "description": "e.g. 'migration', 'fork_inherit'."
            },
            {
              "name": "vetoedAgainstAccountUuid",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "ts",
              "type": "string",
              "required": true,
              "description": "ISO time."
            },
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"history-suppression\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"cause\":\"fork_inherit\",\"ts\":\"2026-10-20T10:00:00.000Z\"}"
        },
        {
          "type": "attribution-snapshot",
          "concept": "workspace-state",
          "summary": "Code-attribution snapshot keyed to a message (which lines Claude authored). Only the latest is kept on load.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "messageId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "(other)",
              "type": "object",
              "required": false,
              "description": "Attribution payload; shape not established."
            }
          ],
          "example": "{\"type\":\"attribution-snapshot\",\"messageId\":\"22222222-2222-4222-8222-222222222222\"}"
        },
        {
          "type": "content-replacement",
          "concept": "compaction",
          "summary": "Records tool-result contents replaced in context (e.g. large results persisted to tool-results/ or cleared), so resume rebuilds the same request.",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "sessionId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "agentId",
              "type": "string",
              "required": false,
              "description": "Routes replacement to a subagent."
            },
            {
              "name": "replacements",
              "type": "array",
              "required": true,
              "description": "Replacement descriptors; shape not established."
            }
          ],
          "example": "{\"type\":\"content-replacement\",\"sessionId\":\"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\"replacements\":[{}]}"
        },
        {
          "type": "observer-ref",
          "concept": "session-lineage",
          "summary": "Reference record for an observer agent (spread of an observer descriptor plus timestamp).",
          "persisted": "only only when the feature is used",
          "fields": [
            {
              "name": "timestamp",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "(observer fields)",
              "type": "object",
              "required": false,
              "description": "Spread from caller; shape not established."
            }
          ],
          "example": "{\"type\":\"observer-ref\",\"timestamp\":\"2026-10-20T10:00:00.000Z\"}"
        }
      ],
      "contentBlocks": [
        {
          "type": "text",
          "concept": "assistant-message",
          "summary": "Plain text block (assistant reply text, or user text).",
          "when": "assistant/user message.content[]",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Done.\"}",
          "notes": ["Also appears as a user content block and inside tool_result.content."]
        },
        {
          "type": "thinking",
          "concept": "reasoning",
          "summary": "Extended-thinking block with signature.",
          "when": "assistant message.content[] (own line)",
          "fields": [
            {
              "name": "signature",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "thinking",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"thinking\",\"thinking\":\"\",\"signature\":\"EqQBCkgIBx...\"}",
          "notes": [
            "thinking text is usually empty (thinkingDisplay 'updates' / omitted display); signature always present."
          ]
        },
        {
          "type": "redacted_thinking",
          "concept": "reasoning",
          "summary": "Redacted thinking block (encrypted data).",
          "when": "assistant message.content[]",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"redacted_thinking\",\"data\":\"EmwKAhgB...\"}"
        },
        {
          "type": "tool_use",
          "concept": "tool-call",
          "summary": "Client tool invocation.",
          "when": "assistant message.content[] (own line)",
          "fields": [
            {
              "name": "caller",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "caller.type",
              "type": "string",
              "required": false,
              "description": "Record discriminator. Values include: direct."
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tool_use\",\"id\":\"toolu_01Example\",\"name\":\"Read\",\"input\":{\"file_path\":\"/home/user/project/README.md\"},\"caller\":{\"type\":\"direct\"}}",
          "notes": [
            "caller {type:'direct'} Values include on all but one; MCP tools are named mcp__<server>__<tool>."
          ]
        },
        {
          "type": "server_tool_use",
          "concept": "tool-call",
          "summary": "Server-side tool invocation (web search/fetch, advisor).",
          "when": "assistant message.content[]",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"server_tool_use\",\"id\":\"srvtoolu_01\",\"name\":\"web_search\",\"input\":{\"query\":\"x\"}}"
        },
        {
          "type": "web_search_tool_result",
          "concept": "tool-result",
          "summary": "Server web-search result block.",
          "when": "assistant message.content[]",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"web_search_tool_result\",\"tool_use_id\":\"srvtoolu_01\",\"content\":[]}"
        },
        {
          "type": "advisor_tool_result",
          "concept": "tool-result",
          "summary": "Result of the server-side advisor tool.",
          "when": "assistant message.content[]",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"advisor_tool_result\",\"tool_use_id\":\"srvtoolu_02\",\"content\":{}}"
        },
        {
          "type": "mcp_tool_use",
          "concept": "tool-call",
          "summary": "API-side MCP connector tool use block.",
          "when": "assistant message.content[]",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"mcp_tool_use\",\"id\":\"mcptoolu_01\",\"name\":\"x\",\"server_name\":\"y\",\"input\":{}}"
        },
        {
          "type": "tool_result",
          "concept": "tool-result",
          "summary": "Result for one tool_use, sent as user content.",
          "when": "user message.content[]",
          "fields": [
            {
              "name": "content",
              "type": "string|array",
              "required": true,
              "description": "—"
            },
            {
              "name": "content[]",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "content[].source",
              "type": "object",
              "required": false,
              "description": "—"
            },
            {
              "name": "content[].text",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "content[].tool_name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "content[].type",
              "type": "string",
              "required": false,
              "description": "Record discriminator."
            },
            {
              "name": "is_error",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "tool_use_id",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tool_result\",\"tool_use_id\":\"toolu_01Example\",\"content\":\"file contents...\",\"is_error\":false}",
          "notes": [
            "content is a string or an array of text/image/tool_reference blocks.",
            "Large outputs: content contains a <persisted-output> wrapper pointing at the tool-results/ sidecar.",
            "Cleared results become '[Old tool result content cleared]' (microcompaction)."
          ]
        },
        {
          "type": "image",
          "concept": "attachment",
          "summary": "Base64 image (pasted by user or returned in a tool_result).",
          "when": "user message.content[] or tool_result.content[]",
          "fields": [
            {
              "name": "source",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "source.data",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "source.media_type",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "source.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator. Values include: base64."
            }
          ],
          "example": "{\"type\":\"image\",\"source\":{\"type\":\"base64\",\"media_type\":\"image/png\",\"data\":\"iVBORw0KGgo...\"}}",
          "notes": ["585 images were inside tool_result.content."]
        },
        {
          "type": "document",
          "concept": "attachment",
          "summary": "PDF/document block.",
          "when": "user content / tool_result content",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"document\",\"source\":{\"type\":\"base64\",\"media_type\":\"application/pdf\",\"data\":\"JVBERi0...\"}}",
          "notes": ["2.1.299: @-mentioned PDF bytes are no longer kept in the session transcript."]
        },
        {
          "type": "search_result",
          "concept": "tool-result",
          "summary": "Search-result content block.",
          "when": "tool_result content",
          "persisted": "conditional",
          "fields": [],
          "example": "{\"type\":\"search_result\",\"source\":\"https://example.com\",\"title\":\"x\",\"content\":[]}"
        },
        {
          "type": "tool_reference",
          "concept": "tool-result",
          "summary": "Reference to a deferred tool definition returned by ToolSearch.",
          "when": "tool_result.content[]",
          "fields": [
            {
              "name": "tool_name",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tool_reference\",\"tool_name\":\"WebFetch\"}"
        },
        {
          "type": "system: text",
          "concept": "system-message",
          "summary": "System-prompt text block, stored inside api-request-blob/api-request-shape (role \"system\").",
          "when": "api-request-blob.message.content[] / api-request-shape.shape.system[]",
          "fields": [
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"You are ...\"}",
          "notes": [
            "Only in request-replay records (since 2.1.300); not part of conversation messages."
          ]
        },
        {
          "type": "system: tool_addition",
          "concept": "session-settings",
          "summary": "Tool definition added mid-conversation, stored in request-replay blobs.",
          "when": "api-request-blob.message.content[] (role system)",
          "fields": [
            {
              "name": "tool",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.definition",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.definition.description",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.definition.eager_input_streaming",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.definition.input_schema",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.definition.name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "tool.type",
              "type": "string",
              "required": true,
              "description": "Record discriminator. Values include: tool_definition."
            }
          ],
          "example": "{\"type\":\"tool_addition\",\"tool\":{\"type\":\"tool_definition\",\"definition\":{\"name\":\"WebFetch\"}}}"
        }
      ],
      "linking": [
        {
          "topic": "ordering",
          "rule": "File order is append order and is NOT conversation order. Lines are appended as they are produced; metadata records are re-appended near the tail; branches from rewinds interleave. Reconstruct conversation order only via parentUuid."
        },
        {
          "topic": "message parent links",
          "rule": "Conversation records (user/assistant/system/attachment) form a tree via uuid -> parentUuid. Each main file starts with an attachment root (parentUuid null). Every other node's parentUuid resolved to an earlier line in the same file. Metadata records have no uuid and are outside the tree."
        },
        {
          "topic": "message parent links",
          "rule": "A streamed assistant response becomes N lines (one content block each) sharing message.id and requestId; each line's parentUuid is the previous line of the same response. Merge consecutive same-message.id assistant lines to recover the API message; usage is repeated, count it once."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "tool_result.tool_use_id = tool_use.id. The user line carrying the result has parentUuid = uuid of the assistant line holding that tool_use and sourceToolAssistantUUID = same uuid. With parallel tool calls the assistant lines chain A1->A2 while result R1 hangs off A1: the assistant line therefore has two children. This is not a user branch."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "toolUseResult on the same user line is the tool's structured result (shape per tool name, string on error). Image base64 in toolUseResult may be blanked (\"\") when identical to the image in message.content (media dedup, Ie()/Epn() refill on read)."
        },
        {
          "topic": "turns",
          "rule": "A human turn starts at a user line with promptSource typed/queued (origin.kind human) and ends with system/turn_duration (durationMs, messageCount). promptId groups the prompt and all its descendants. system/stop_hook_summary follows when Stop hooks run."
        },
        {
          "topic": "subagents",
          "rule": "Parent assistant tool_use (Agent/Task, or Skill fork) id == subagents/agent-<id>.meta.json toolUseId. The Agent toolUseResult has agentId and outputFile. Subagent file: every conversation line has isSidechain:true, agentId = filename id, sessionId = parent session id; first line parentUuid null. Forked subagents start with a fork-context-ref pointing at parentSessionId + parentLastUuid + contextLength instead of copying the prefix. Subagent api-request/blob/shape/content-replacement records are routed to the subagent file (route-by-agent)."
        },
        {
          "topic": "compaction",
          "rule": "system/compact_boundary has parentUuid:null (new chain root) and logicalParentUuid = last pre-compaction node. The next user line has isCompactSummary:true + isVisibleInTranscriptOnly:true and holds the summary. compactMetadata.preservedSegment {headUuid, anchorUuid, tailUuid} and preservedMessages.uuids name kept messages (52/52 resolved). On load, 'transcript' and 'boundary-cleared' records before the last boundary are dropped; 'last-wins'/'accumulate' metadata survive."
        },
        {
          "topic": "compaction",
          "rule": "Microcompaction replaces old tool_result content with '[Old tool result content cleared]' or a <persisted-output> preview; content-replacement records log those substitutions so resume reproduces the same request."
        },
        {
          "topic": "branches/rewind",
          "rule": "Rewind/edit appends new nodes whose parentUuid points back into the tree; abandoned branches stay in the file. The active leaf is the leafUuid of the last last-prompt record (explicit:true for user-chosen leaf, rewound:true after /rewind); a last-prompt with leafUuid:null + explicit:true withdraws the leaf. Without a usable last-prompt the loader picks the newest-timestamp non-sidechain message. Walk parentUuid from the leaf to the root, merging same-message.id assistant siblings and re-attaching parallel tool results."
        },
        {
          "topic": "forks",
          "rule": "/branch (fork) writes a NEW <new-session-id>.jsonl: copies the selected path with original uuids, linearised parentUuid, new sessionId, isSidechain:false and forkedFrom {sessionId, messageUuid}; carries content-replacement, relocated, memory-mode, atis-latch and history-suppression(cause fork_inherit) forward."
        },
        {
          "topic": "resume",
          "rule": "--resume/--continue reopen and keep appending to the same <session-id>.jsonl (hook_success attachments with hookName SessionStart:resume appear). A continued-in record can point to a successor session."
        },
        {
          "topic": "sidecar references",
          "rule": "file-history-snapshot.snapshot.trackedFileBackups[path].backupFileName -> ~/.claude/file-history/<sessionId>/<name>; file-history-delta.messageId/snapshotMessageId -> user uuid; toolUseResult.persistedOutputPath -> <session-id>/tool-results/<id>.txt; api-request.shapeHash -> api-request-shape; api-request.tail[] -> api-request-blob.hash; api-request.base -> earlier api-request.id; assistant.requestRef -> api-request.id."
        }
      ],
      "versioning": "Every conversation record carries version (Claude Code semver of the writer); metadata records do not. There is no file-level header or schema version. Known boundaries: api-request / api-request-blob / api-request-shape records and assistant.requestRef appear from 2.1.300 (changelog 2.1.300: 'record each API request's system prompt, tools and parameters'); params.safeguards[].classifier_context stored only 2.1.300–2.1.303 (changelog 2.1.304); subagent placeholder usage/null stop_reason fixed 2.1.307; renderedRole on attachments from 2.1.285; requestedModel from 2.1.295; permissionDecision from 2.1.293; sandboxed from 2.1.307; thinkingDisplay from 2.1.296; file-history pruning 2.1.208 (changelog).",
      "usage": [
        {
          "field": "assistant.message.usage.input_tokens",
          "meaning": "Uncached input tokens of the API response. Repeated on every line of a split response — dedupe by message.id."
        },
        {
          "field": "assistant.message.usage.cache_creation_input_tokens / cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens",
          "meaning": "Prompt-cache write tokens, total and by TTL."
        },
        {
          "field": "assistant.message.usage.cache_read_input_tokens",
          "meaning": "Prompt-cache read tokens."
        },
        {
          "field": "assistant.message.usage.output_tokens / output_tokens_details.thinking_tokens",
          "meaning": "Output tokens and the thinking share."
        },
        {
          "field": "assistant.message.usage.iterations[]",
          "meaning": "Per-iteration usage when the server ran multiple sampling iterations (e.g. server tools/advisor)."
        },
        {
          "field": "assistant.message.usage.server_tool_use.web_search_requests / web_fetch_requests",
          "meaning": "Server tool call counts."
        },
        {
          "field": "assistant.message.usage.service_tier / speed / inference_geo / fallback_credit",
          "meaning": "Tier and routing metadata."
        },
        {
          "field": "cost-state.totalCostUSD, modelUsage.<model>.costUSD",
          "meaning": "Client-estimated cumulative cost (last record wins)."
        },
        {
          "field": "attachment/queued_command.attachment.usage {totalTokens, toolUses, durationMs}",
          "meaning": "Usage summary of a finished background task/subagent delivered as a notification."
        },
        {
          "field": "system/compact_boundary.compactMetadata.preTokens / postTokens / cumulativeDroppedTokens",
          "meaning": "Context size before/after compaction."
        }
      ],
      "gotchas": [
        "Assistant usage is duplicated on every split line of one response; summing per line over-counts tokens 2x on average.",
        "parentUuid chains are not linear: parallel tool calls make the assistant line a parent of both the next assistant block and its own tool_result. Following only the last child loses results.",
        "Metadata (ai-title, last-prompt, mode, permission-mode, atis-latch, custom-title, tag, pr-link, ...) is re-appended to the tail repeatedly so tail-window readers find it; expect thousands of duplicates and take the last.",
        "Metadata records have no uuid, version or (mostly) timestamp; do not require the conversation envelope on every line.",
        "In subagent files sessionId is the parent session id, not the file stem; use agentId / filename.",
        "api-request.version is a replay-format number, not the Claude Code version string; api-request-blob.message.role can be \"system\".",
        "message.content can be a string or an array; user tool_result content can be a string or an array of text/image/tool_reference.",
        "Thinking blocks often have empty text with a valid signature (display mode updates); do not treat as corruption.",
        "Subagent transcripts before 2.1.307 recorded placeholder usage and null stop_reason for streamed responses.",
        "Progress records are not written by current builds but may exist in older files; their uuids can be parents of real messages, so re-parent through them rather than dropping the child.",
        "compact_boundary has parentUuid null: walking from the leaf stops there; use logicalParentUuid to stitch pre-compaction history.",
        "A torn last line is possible after a crash (2.1.300 fix); tolerate an unparsable final line.",
        "The session directory <session-id>/ may exist without the .jsonl being the only data: tool-results and subagents hold content referenced from the transcript.",
        "cwd, gitBranch, slug, prompts, file paths and tool inputs are private user data embedded in nearly every line.",
        "Claude Code strips envelope fields (cwd, gitBranch, version, userType, entrypoint, promptId, +requestId on assistant) for some storage paths and re-fill them from context on read (A3s/H8n); remote/storage-backed transcripts may lack them."
      ],
      "evidence": [
        "claude-sessions-docs",
        "transcript-format-claude-code-2-1-310-bundle-examined-local-transcripts-written-by-2-1-281-2-1-310-local",
        "transcript-format-claude-code-github-com-anthropics-claude-code-blob-main-changelog-md",
        "transcripts-claude-code-code-claude-com-docs-en-claude-directory"
      ],
      "references": {
        "location": "https://code.claude.com/docs/en/sessions#where-transcripts-are-stored"
      }
    },
    {
      "harness": "cursor-agent",
      "variant": "current",
      "default": true,
      "version": "2026.10.12-d47ca18",
      "stability": "live-observed",
      "container": "One SQLite database per chat (`store.db`, WAL mode). Table `meta` holds one row whose value is hex-encoded JSON; table `blobs` maps a SHA-256 id to bytes that are protobuf messages, JSON prompt messages or raw file contents. A simplified JSON Lines copy is written per project.",
      "discriminator": "Blobs carry no type tag: a blob's type follows from the field that references it, starting at `latestRootBlobId` in `meta`. Inside protobuf messages, `oneof` cases pick the variant; inside JSON prompt messages, `role` then `content[].type`. In the JSON Lines copy, `type` when present, otherwise `role`.",
      "layout": [
        {
          "path": "~/.cursor/ (moves with CURSOR_CONFIG_DIR, else $XDG_CONFIG_HOME/cursor)",
          "kind": "other",
          "description": "CLI config root; chats/ and acp-sessions/ live under it."
        },
        {
          "path": "~/.cursor/chats/<md5hex(path.resolve(cwd))>/",
          "kind": "other",
          "description": "Per-workspace folder; name is the lowercase hex MD5 of the resolved absolute working directory (no trailing-slash normalisation beyond path.resolve)."
        },
        {
          "path": "~/.cursor/chats/<md5>/<chatId>/",
          "kind": "other",
          "description": "One folder per chat; <chatId> is a v4 UUID equal to meta.agentId. Deleted automatically on dispose if the chat has no root and no blobs."
        },
        {
          "path": "~/.cursor/chats/<md5>/<chatId>/store.db (+ store.db-wal, store.db-shm)",
          "kind": "database",
          "description": "SQLite (WAL mode, user_version=1) with tables meta(key TEXT PK, value TEXT) and blobs(id TEXT PK, data BLOB). Holds the whole conversation as a content-addressed blob graph rooted at meta.latestRootBlobId. This is the source of truth."
        },
        {
          "path": "~/.cursor/chats/<md5>/<chatId>/meta.json",
          "kind": "sidecar",
          "description": "Listing sidecar for the resume picker: {schemaVersion:1, createdAtMs, updatedAtMs?, hasConversation, title?, isSubagent?, cwd?}. Derived from store.db metadata; backfilled from store.db if missing."
        },
        {
          "path": "~/.cursor/chats/<md5>/<chatId>/prompt_history.json",
          "kind": "history",
          "description": "Up-arrow input history for this chat: a JSON array of strings, newest first, de-duplicated, max 500."
        },
        {
          "path": "~/.cursor/projects/<slug(cwd)>/ (moves with CURSOR_DATA_DIR)",
          "kind": "other",
          "description": "Project data dir shared with the Cursor editor; slug = cwd with every non-alphanumeric run replaced by '-', leading/trailing '-' trimmed. Also holds editor/CLI data unrelated to transcripts (mcps/, terminals/, canvases/, rules/, repo.json, worker.log, ...)."
        },
        {
          "path": "~/.cursor/projects/<slug>/agent-transcripts/<chatId>/<chatId>.jsonl",
          "kind": "transcript",
          "description": "Lossy, human-oriented JSONL mirror regenerated from store.db's prompt-message JSON blobs: user/assistant lines plus turn_ended lines. No tool results, no system prompt, no ids. <chatId> is encodeURIComponent'd with '%' -> '_' and truncated to 200 chars."
        },
        {
          "path": "~/.cursor/projects/<slug>/agent-transcripts/<parentChatId>/subagents/<subagentId>.jsonl",
          "kind": "transcript",
          "description": "Same JSONL mirror for each subagent found in the parent root's subagent_states / subagent_state_refs."
        },
        {
          "path": "~/.cursor/projects/<slug>/agent-transcripts/<chatId>.jsonl | .txt (legacy flat layout)",
          "kind": "transcript",
          "description": "Legacy path still probed by readers (paths.pr includeLegacy); a .txt rendering exists in the writer but the CLI configures writeText:false."
        },
        {
          "path": "~/.cursor/projects/<slug>/terminals/<n>.txt",
          "kind": "sidecar",
          "description": "Shell output files referenced from shell tool results (terminalsFolder / outputLocation.filePath). Not part of the blob graph."
        },
        {
          "path": "~/.cursor/acp-sessions/<sessionId>/meta.json (+ store.db)",
          "kind": "sidecar",
          "description": "Sessions created through `agent acp`: same store.db format at acp-sessions/<id>/store.db plus meta.json {schemaVersion:1, cwd, title?}."
        }
      ],
      "envelope": [
        {
          "name": "blobs.id",
          "type": "string (64 hex)",
          "required": true,
          "description": "SHA-256 of blobs.data, lowercase hex. Root blobs are hashed by the CLI; other blob ids are chosen by the server"
        },
        {
          "name": "blobs.data",
          "type": "bytes",
          "required": true,
          "description": "Payload. Type is NOT stored; it is implied by which field references the blob. Heuristic: first byte '{' => JSON prompt message (or raw file that happens to be JSON); otherwise protobuf or raw bytes."
        },
        {
          "name": "meta['0']",
          "type": "string (hex of UTF-8 JSON)",
          "required": true,
          "description": "Chat metadata object; see record 'meta / 0'."
        }
      ],
      "records": [
        {
          "type": "meta / '0'",
          "concept": "session-header",
          "summary": "Chat metadata: id, title, mode, timestamps and the pointer to the current conversation root.",
          "when": "Created on store open (defaults), rewritten (INSERT OR REPLACE, debounced via microtask) whenever any key changes, e.g. after every checkpoint.",
          "fields": [
            {
              "name": "agentId",
              "type": "string (uuid)",
              "required": true,
              "description": "Chat id; equals the chat folder name."
            },
            {
              "name": "latestRootBlobId",
              "type": "string (64 hex) | ''",
              "required": true,
              "description": "Blob id of the current ConversationStateStructure root. Empty string when the chat never got a checkpoint."
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "Chat title; default 'New Agent'; forks get '<name> (forked)'."
            },
            {
              "name": "createdAt",
              "type": "number (ms epoch)",
              "required": true,
              "description": "Creation time (readers normalise seconds/micro/nanoseconds too)."
            },
            {
              "name": "mode",
              "type": "enum(default|plan|debug|search)",
              "required": true,
              "description": "UI mode; legacy 'auto-run' is read as default + isRunEverything=true. Values include default, search."
            },
            {
              "name": "isRunEverything",
              "type": "boolean",
              "required": true,
              "description": "Auto-run/yolo flag."
            },
            {
              "name": "approvalMode",
              "type": "enum(allowlist|unrestricted|auto-review)",
              "required": false,
              "description": "Approval policy. Values include unrestricted."
            },
            {
              "name": "lastUsedModel",
              "type": "string",
              "required": false,
              "description": "Model id last used."
            },
            {
              "name": "lastDebugServerPort",
              "type": "integer",
              "required": false,
              "description": "Debug-mode server port."
            },
            {
              "name": "currentPlanUri",
              "type": "string",
              "required": false,
              "description": "Plan file URI in plan mode."
            },
            {
              "name": "subagentInfo",
              "type": "object {parentAgentId, rootParentAgentId, toolCallId, typeName}",
              "required": false,
              "description": "Set when this store belongs to a subagent run with its own store."
            },
            {
              "name": "blobEncryptionKey",
              "type": "string (64 hex)",
              "required": false,
              "description": "Random 32-byte key generated in defaults by this build; its purpose is not known."
            }
          ],
          "example": "{\"agentId\":\"00000000-0000-4000-8000-000000000001\",\"latestRootBlobId\":\"aa…(64 hex)\",\"name\":\"Example chat\",\"mode\":\"default\",\"isRunEverything\":false,\"createdAt\":1760000000000,\"lastUsedModel\":\"example-model\"} (stored as hex of this JSON)",
          "notes": [
            "Value is hex-encoded: bytes.fromhex(value).decode('utf-8') then JSON.parse.",
            "Keys outside the zod schema are dropped on load."
          ]
        },
        {
          "type": "blob: agent.v1.ConversationStateStructure (root checkpoint)",
          "concept": "session-settings",
          "summary": "The conversation checkpoint: ordered lists of blob ids for the model prompt and for UI turns, plus todos, token budget, file snapshots, subagents and compaction state.",
          "when": "Every checkpoint the server streams (AgentServerMessage.conversation_checkpoint_update) is serialized, SHA-256 hashed and stored as a new blob; meta.latestRootBlobId is then pointed at it. Older roots are never deleted.",
          "fields": [
            {
              "name": "1 root_prompt_messages_json",
              "type": "repeated bytes (blob ids)",
              "required": false,
              "description": "Ordered ids of JSON prompt-message blobs = the exact model context (system, user, assistant, tool). Primary source for a faithful transcript."
            },
            {
              "name": "8 turns",
              "type": "repeated bytes (blob ids)",
              "required": false,
              "description": "Ordered ids of ConversationTurnStructure blobs (UI/turn view)."
            },
            {
              "name": "3 todos",
              "type": "repeated bytes (blob ids)",
              "required": false,
              "description": "TodoItem blobs."
            },
            {
              "name": "4 pending_tool_calls",
              "type": "repeated string",
              "required": false,
              "description": "Tool call ids still awaiting a result."
            },
            {
              "name": "5 token_details",
              "type": "ConversationTokenDetails {1 used_tokens u32, 2 max_tokens u32, 3 breakdown PromptTokenBreakdownSnapshot{total_used_tokens,max_tokens,categories[{id,label,character_count,estimated_tokens}]}, 4 prompt_context_usage_tree}",
              "required": false,
              "description": "Context-window occupancy snapshot (not billing usage)."
            },
            {
              "name": "6 summary",
              "type": "bytes (blob id)",
              "required": false,
              "description": "ConversationSummary blob {1 summary string}."
            },
            {
              "name": "7 plan",
              "type": "bytes (blob id)",
              "required": false,
              "description": "Plan blob; payload type not traced (opaque)."
            },
            {
              "name": "9 previous_workspace_uris",
              "type": "repeated string",
              "required": false,
              "description": "Workspace URIs used earlier."
            },
            {
              "name": "10 mode",
              "type": "enum AgentMode",
              "required": false,
              "description": "AGENT_MODE_{UNSPECIFIED=0,AGENT=1,ASK=2,PLAN=3,DEBUG=4,TRIAGE=5,MULTITASK=7,CUSTOM=8}."
            },
            {
              "name": "11 summary_archive",
              "type": "bytes (blob id)",
              "required": false,
              "description": "Legacy single archive pointer."
            },
            {
              "name": "12 file_states",
              "type": "map<string path, bytes blob id>",
              "required": false,
              "description": "Legacy file snapshot map."
            },
            {
              "name": "13 summary_archives",
              "type": "repeated bytes (blob ids)",
              "required": false,
              "description": "ConversationSummaryArchive blobs, one per compaction."
            },
            {
              "name": "14 turn_timings",
              "type": "repeated StepTiming {1 duration_ms u64, 2 timestamp_ms u64}",
              "required": false,
              "description": "Per-turn timings."
            },
            {
              "name": "15 file_states_v2",
              "type": "map<string path, FileStateStructure {1 content bytes?, 2 initial_content bytes?}>",
              "required": false,
              "description": "Per-file snapshots; both fields are 32-byte blob ids of raw file bytes. Used by rewind to restore files."
            },
            {
              "name": "16 subagent_states",
              "type": "map<string subagentId, SubagentPersistedState>",
              "required": false,
              "description": "Inline subagent conversations (each has its own nested ConversationStateStructure)."
            },
            {
              "name": "17 self_summary_count",
              "type": "uint32",
              "required": false,
              "description": "Number of self-summarisations."
            },
            {
              "name": "18 read_paths",
              "type": "repeated string",
              "required": false,
              "description": "Paths the agent has read (contains user paths)."
            },
            {
              "name": "19 active_branch_name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "20 plans",
              "type": "map<string, PlanRegistryEntry {1 id, 2 path}>",
              "required": false,
              "description": "—"
            },
            {
              "name": "21 tracked_git_repo_branches",
              "type": "repeated TrackedGitRepo {1 repo_path, 2 branch_name}",
              "required": false,
              "description": "—"
            },
            {
              "name": "22 agent_type",
              "type": "string",
              "required": false,
              "description": "Values include on every current-format root."
            },
            {
              "name": "23 communicate_update_history / 25 communicate_update_final_summary / 28 communicate_update_completed_subtitle / 29 communicate_update_states_by_parent_tool_call_id",
              "type": "various",
              "required": false,
              "description": "Progress-update tool state (cloud/background agents)."
            },
            {
              "name": "24 subagent_threads",
              "type": "map<string,string>",
              "required": false,
              "description": "—"
            },
            {
              "name": "26 conversation_started_timestamp_ms",
              "type": "uint64",
              "required": false,
              "description": "—"
            },
            {
              "name": "27 conversation_started_time_zone",
              "type": "string",
              "required": false,
              "description": "IANA zone."
            },
            {
              "name": "30 subagent_runs_by_parent_tool_call_id",
              "type": "map<string, SubagentRunState {parent_tool_call_id, subagent_id?, environment, status SubagentRunStatus, title?, detail?, transcript_path?, output_path?, completed_timestamp_ms?, completion_reason?}>",
              "required": false,
              "description": "SubagentRunStatus: UNSPECIFIED, RUNNING, BACKGROUNDED, SUCCESS, ERROR, ABORTED."
            },
            {
              "name": "31 subagent_state_refs",
              "type": "map<string subagentId, bytes blob id>",
              "required": false,
              "description": "Out-of-line SubagentPersistedState blobs (newer alternative to field 16)."
            },
            {
              "name": "32 goal_state",
              "type": "GoalState",
              "required": false,
              "description": "—"
            },
            {
              "name": "33 is_root_project_conversation",
              "type": "bool",
              "required": false,
              "description": "—"
            },
            {
              "name": "34 completed_ask_question_tool_call_ids",
              "type": "repeated string",
              "required": false,
              "description": "—"
            },
            {
              "name": "35 durable_skill_blocks / 36 durable_custom_mode_id",
              "type": "repeated string / string",
              "required": false,
              "description": "—"
            },
            {
              "name": "37 message_count_at_last_compaction",
              "type": "uint32",
              "required": false,
              "description": "—"
            },
            {
              "name": "38 recent_user_message_ids / 39 recent_user_message_ids_older_turn_count",
              "type": "repeated string / uint32",
              "required": false,
              "description": "—"
            },
            {
              "name": "40 turn_telemetry",
              "type": "TurnTelemetryState {completed_turn_count_capped, last_completed_turn_timestamp_ms?}",
              "required": false,
              "description": "—"
            },
            {
              "name": "42 mentioned_agent_ids",
              "type": "repeated string",
              "required": false,
              "description": "—"
            },
            {
              "name": "2 (unknown)",
              "type": "length-delimited",
              "required": false,
              "description": "Field number 2 is absent from this build's descriptor but present in older roots: a removed field. Skip unknown fields."
            }
          ],
          "example": "(protobuf) {root_prompt_messages_json:[<32B>,<32B>], turns:[<32B>], token_details:{used_tokens:12000,max_tokens:200000}, mode:AGENT_MODE_AGENT, agent_type:\"example\"}",
          "notes": ["Field order in the descriptor is not numeric; decode by field number."]
        },
        {
          "type": "blob: agent.v1.ConversationTurnStructure / agent_conversation_turn",
          "concept": "turn-start",
          "summary": "One user turn: pointer to the user message and ordered pointers to the assistant steps it produced.",
          "when": "Written by the server when a turn starts and re-written (new blob id) as steps are appended.",
          "fields": [
            {
              "name": "1 agent_conversation_turn.1 user_message",
              "type": "bytes (blob id)",
              "required": true,
              "description": "UserMessage blob."
            },
            {
              "name": "…2 steps",
              "type": "repeated bytes (blob ids)",
              "required": false,
              "description": "ConversationStep blobs in order."
            },
            {
              "name": "…3 request_id",
              "type": "string (uuid)",
              "required": false,
              "description": "Server request id; matches JSON user message providerOptions.cursor.requestId."
            },
            {
              "name": "…4 encrypted_model",
              "type": "string",
              "required": false,
              "description": "Opaque encrypted model identifier (258/263 turns)."
            },
            {
              "name": "…5 dynamic_tool_count / 9 dynamic_tool_names",
              "type": "uint32 / repeated string",
              "required": false,
              "description": "—"
            },
            {
              "name": "…6 send_message_step_indices / 13 assistant_text_step_indices / 14 assistant_text_steps_recorded",
              "type": "repeated uint32 / bool",
              "required": false,
              "description": "Indices into steps."
            },
            {
              "name": "…7 routed_model_display_name",
              "type": "string",
              "required": false,
              "description": "Display name when auto-routed."
            },
            {
              "name": "…8 subagent_dispatch_steps",
              "type": "repeated SubagentDispatchStep {step_index, tool_call_id, tool, backgrounded}",
              "required": false,
              "description": "—"
            },
            {
              "name": "…10 user_message_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "…11 long_reasoning_reminder / 12 long_reasoning_reminder_exposure_logged",
              "type": "message / bool",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {agent_conversation_turn:{user_message:<32B>, steps:[<32B>,<32B>], request_id:\"00000000-0000-4000-8000-000000000002\"}}"
        },
        {
          "type": "blob: agent.v1.ConversationTurnStructure / shell_conversation_turn",
          "concept": "tool-call",
          "summary": "A user-run shell command turn (shell mode), stored as two blobs: command and output.",
          "when": "When the user runs a shell command directly instead of prompting the agent.",
          "persisted": "only user shell-mode commands",
          "fields": [
            {
              "name": "2 shell_conversation_turn.1 shell_command",
              "type": "bytes (blob id)",
              "required": true,
              "description": "ShellCommand {1 command string}."
            },
            {
              "name": "…2 shell_output",
              "type": "bytes (blob id)",
              "required": true,
              "description": "ShellOutput {1 stdout, 2 stderr, 3 exit_code int32}."
            }
          ],
          "example": "(protobuf) {shell_conversation_turn:{shell_command:<32B>, shell_output:<32B>}}"
        },
        {
          "type": "blob: agent.v1.UserMessage",
          "concept": "user-message",
          "summary": "The user's prompt as typed, with mode, attached context and the id of the root checkpoint that preceded it.",
          "when": "Once per turn.",
          "fields": [
            {
              "name": "1 text",
              "type": "string",
              "required": true,
              "description": "Raw prompt text (without the <user_query> wrapper used in the JSON prompt message)."
            },
            {
              "name": "2 message_id",
              "type": "string (uuid)",
              "required": true,
              "description": "—"
            },
            {
              "name": "3 selected_context",
              "type": "SelectedContext",
              "required": false,
              "description": "Attached context: selected_images[] (SelectedImage {oneof data_or_blob_id: 1 blob_id | 8 data | 9 blob_id_with_data | 10 prompt_upload_ref; uuid, path, dimension, mime_type}), files, code_selections, terminals, folders, external_links, cursor_rules, git diffs/commits, past_chats, pull requests, subagents, browsers, documents, skills, … (28 fields)."
            },
            {
              "name": "4 mode",
              "type": "enum AgentMode",
              "required": true,
              "description": "Values include AGENT, ASK."
            },
            {
              "name": "5 is_simulated_msg / 9 simulated_msg_reason / 15 simulated_message_metadata",
              "type": "bool / enum SimulatedMsgReason (35 values) / message",
              "required": false,
              "description": "System-injected 'user' messages (e.g. BACKGROUND_TASK_COMPLETION, PLAN_EXECUTION, USER_QUEUED_TO_SUBAGENT, GOAL_CONTINUATION)."
            },
            {
              "name": "10 conversation_state_blob_id",
              "type": "bytes (blob id)",
              "required": true,
              "description": "Root checkpoint as it was before this turn; used as the rewind anchor."
            },
            {
              "name": "17 thread_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "18 text_blob_id / 19 rich_text_blob_id",
              "type": "bytes (blob id)",
              "required": false,
              "description": "Out-of-line large text."
            },
            {
              "name": "8 rich_text",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "21 hook_additional_contexts",
              "type": "repeated HookAdditionalContext {hook_event_name, content}",
              "required": false,
              "description": "Context added by hooks."
            },
            {
              "name": "24 turn_steer",
              "type": "bool",
              "required": false,
              "description": "Message sent while the agent was running (steering)."
            },
            {
              "name": "25 started_at_ms / 26 completed_at_ms",
              "type": "uint64",
              "required": false,
              "description": "—"
            },
            {
              "name": "27 sent_by_agent_id / 29 sender / 28 sent_by_voice_call / 30 forked_context / 31 reply_to",
              "type": "various",
              "required": false,
              "description": "Agent-to-agent and multi-agent provenance."
            },
            {
              "name": "6,7,11,13,14,16,22,23",
              "type": "various",
              "required": false,
              "description": "best_of_n_group_id, try_use_best_of_n_promotion, subagent_system_reminder, triggering_user_info, execute_plan_info, prompt_reference_id, custom_mode_intent, project_details."
            }
          ],
          "example": "(protobuf) {text:\"Example prompt\", message_id:\"00000000-0000-4000-8000-000000000003\", mode:AGENT_MODE_AGENT, conversation_state_blob_id:<32B>, thread_id:\"…\"}"
        },
        {
          "type": "blob: agent.v1.ConversationStep / assistant_message",
          "concept": "assistant-message",
          "summary": "A visible assistant text segment.",
          "when": "Per assistant text output within a turn.",
          "fields": [
            {
              "name": "1 assistant_message.1 text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "…2 started_at_ms / 3 completed_at_ms",
              "type": "uint64",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {assistant_message:{text:\"Done.\"}}"
        },
        {
          "type": "blob: agent.v1.ConversationStep / thinking_message",
          "concept": "reasoning",
          "summary": "A reasoning step as shown in the UI.",
          "when": "Per reasoning block.",
          "fields": [
            {
              "name": "3 thinking_message.1 text",
              "type": "string",
              "required": true,
              "description": "Often empty or summary text when the provider redacts reasoning."
            },
            {
              "name": "…2 duration_ms",
              "type": "uint32",
              "required": true,
              "description": "—"
            },
            {
              "name": "…3 started_at_ms / 4 completed_at_ms",
              "type": "uint64",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {thinking_message:{text:\"\", duration_ms:1200}}"
        },
        {
          "type": "blob: agent.v1.ConversationStep / tool_call",
          "concept": "tool-call",
          "summary": "A tool invocation with its structured arguments AND result in one message (ToolCall oneof `tool`, 68 cases).",
          "when": "Re-written (new blob) as the call progresses from started to completed; the turn's steps list is updated to the newest id.",
          "fields": [
            {
              "name": "2 tool_call.<case>",
              "type": "oneof tool",
              "required": true,
              "description": "One of: shell_tool_call, delete_tool_call, glob_tool_call, grep_tool_call, read_tool_call, update_todos_tool_call, read_todos_tool_call, edit_tool_call, ls_tool_call, read_lints_tool_call, mcp_tool_call, sem_search_tool_call, create_plan_tool_call, web_search_tool_call, task_tool_call, list_mcp_resources_tool_call, read_mcp_resource_tool_call, apply_agent_diff_tool_call, ask_question_tool_call, fetch_tool_call, switch_mode_tool_call, generate_image_tool_call, record_screen_tool_call, computer_use_tool_call, write_shell_stdin_tool_call, reflect_tool_call, setup_vm_environment_tool_call, truncated_tool_call, start_grind_execution_tool_call, start_grind_planning_tool_call, web_fetch_tool_call, report_bugfix_results_tool_call, ai_attribution_tool_call, pr_management_tool_call, mcp_auth_tool_call, await_tool_call, blame_by_file_path_tool_call, get_mcp_tools_tool_call, report_bug_tool_call, set_active_branch_tool_call, communicate_update_tool_call, send_final_summary_tool_call, replace_env_tool_call, edit_pr_labels_tool_call, record_ci_investigation_findings_tool_call, send_message_tool_call, fetch_cloud_agent_data_tool_call, send_to_user_tool_call, pi_read_tool_call, pi_bash_tool_call, pi_edit_tool_call, pi_write_tool_call, pi_grep_tool_call, pi_find_tool_call, pi_ls_tool_call, connect_scm_tool_call, search_conversations_tool_call, create_goal_tool_call, update_goal_tool_call, get_agent_status_tool_call, send_to_agent_tool_call, read_agent_transcript_tool_call, create_agent_tool_call, stop_agent_tool_call, write_canvas_tool_call, read_canvas_tool_call, generate_video_tool_call, x_search_tool_call. Each case is a <Name>ToolCall {1 args <Name>Args, 2 result <Name>Result} (some add description etc.)."
            },
            {
              "name": "…<case>.result",
              "type": "oneof result",
              "required": false,
              "description": "Typical cases: success | error | rejected | failure | timeout | spawn_error | permission_denied (shell). Absent while pending."
            },
            {
              "name": "…57 tool_call_id",
              "type": "string",
              "required": false,
              "description": "e.g. 'tool_<uuid>'; equals JSON tool-call toolCallId."
            },
            {
              "name": "…59 started_at_ms / 60 completed_at_ms",
              "type": "uint64",
              "required": false,
              "description": "—"
            },
            {
              "name": "…54 hook_additional_contexts",
              "type": "repeated HookAdditionalContext",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {tool_call:{read_tool_call:{args:{path:\"src/example.ts\"}, result:{success:{path:\"src/example.ts\", total_lines:10, content:\"…\"}}}, tool_call_id:\"tool_00000000-0000-4000-8000-000000000004\"}}",
          "notes": [
            "Edit results carry before_full_file_content and after_full_file_content (whole files).",
            "ReadToolSuccess may hold content inline or as content_blob_id (raw bytes blob).",
            "TaskSuccess.conversation_steps embeds the subagent's ConversationSteps inline."
          ]
        },
        {
          "type": "blob: agent.v1.TodoItem",
          "concept": "metadata-other",
          "summary": "One todo-list entry.",
          "when": "When the todo tool updates the list.",
          "persisted": "only todo tool used",
          "fields": [
            {
              "name": "1 id",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "2 content",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "3 status",
              "type": "enum TodoStatus(UNSPECIFIED,PENDING,IN_PROGRESS,COMPLETED,CANCELLED)",
              "required": true,
              "description": "—"
            },
            {
              "name": "4 created_at / 5 updated_at",
              "type": "int64 ms",
              "required": true,
              "description": "—"
            },
            {
              "name": "6 dependencies",
              "type": "repeated string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {id:\"1\", content:\"Write tests\", status:TODO_STATUS_PENDING, created_at:1760000000000, updated_at:1760000000000}"
        },
        {
          "type": "blob: agent.v1.ConversationSummary",
          "concept": "summary",
          "summary": "Running conversation summary text.",
          "when": "After summarisation.",
          "persisted": "only summarisation",
          "fields": [
            {
              "name": "1 summary",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "(protobuf) {summary:\"Summary of earlier work\"}"
        },
        {
          "type": "blob: agent.v1.ConversationSummaryArchive",
          "concept": "compaction",
          "summary": "Archive of the prompt messages replaced by a compaction, plus the summary that replaced them.",
          "when": "On /summarize or automatic summarisation; appended to root.summary_archives.",
          "persisted": "only compaction",
          "fields": [
            {
              "name": "1 summarized_messages",
              "type": "repeated bytes (blob ids)",
              "required": true,
              "description": "The JSON prompt-message blobs that were compacted away."
            },
            {
              "name": "2 summary",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "3 window_tail",
              "type": "uint32",
              "required": true,
              "description": "Number of trailing messages kept."
            },
            {
              "name": "4 summary_message",
              "type": "bytes (blob id)",
              "required": true,
              "description": "JSON prompt message carrying the summary (providerOptions.cursor.isSummary=true)."
            }
          ],
          "example": "(protobuf) {summarized_messages:[<32B>,<32B>], summary:\"…\", window_tail:4, summary_message:<32B>}"
        },
        {
          "type": "blob: agent.v1.SubagentPersistedState",
          "concept": "session-lineage",
          "summary": "A subagent's own conversation state, keyed by subagent id from the parent root.",
          "when": "When a Task/subagent runs; inline in root field 16 or out-of-line via field 31.",
          "persisted": "only subagents",
          "fields": [
            {
              "name": "1 conversation_state",
              "type": "ConversationStateStructure",
              "required": true,
              "description": "Same structure as the parent; its blob ids live in the parent's store.db."
            },
            {
              "name": "2 created_timestamp_ms / 3 last_used_timestamp_ms",
              "type": "uint64",
              "required": true,
              "description": "—"
            },
            {
              "name": "4 subagent_type",
              "type": "SubagentType (oneof type: unspecified | custom{name} | …)",
              "required": true,
              "description": "—"
            },
            {
              "name": "5 model_id",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "6 environment",
              "type": "SubagentExecutionEnvironment",
              "required": true,
              "description": "—"
            },
            {
              "name": "7 cloud_subagent",
              "type": "CloudSubagentReference {bc_id, transcript_path?}",
              "required": false,
              "description": "—"
            },
            {
              "name": "8 first_class_bc_id / 9 cloud_requested_environment_build_id / 10 machine",
              "type": "string / string / TargetMachine",
              "required": false,
              "description": "—"
            }
          ],
          "example": "(protobuf) {conversation_state:{…}, created_timestamp_ms:1760000000000, last_used_timestamp_ms:1760000005000, subagent_type:{unspecified:{}}, model_id:\"example-model\"}"
        },
        {
          "type": "blob: raw file content",
          "concept": "workspace-state",
          "summary": "Raw bytes of a file snapshot (FileStateStructure.content / initial_content) or of read-tool output (ReadToolSuccess.content_blob_id), or image data (SelectedImage.blob_id).",
          "when": "When the agent edits/reads files; used by rewind to restore files.",
          "persisted": "only file edits/reads",
          "fields": [
            {
              "name": "(whole blob)",
              "type": "bytes",
              "required": true,
              "description": "No envelope. May itself be valid JSON (e.g. a package.json) - do not classify by first byte alone."
            }
          ],
          "example": "(raw bytes) export const example = 1;\\n"
        },
        {
          "type": "blob: superseded root checkpoints and steps (unreachable)",
          "concept": "metadata-other",
          "summary": "Older ConversationStateStructure roots and superseded turn/step/user-message blobs that the latest root no longer references.",
          "when": "Every checkpoint leaves the previous root in place; steps re-written with new content leave the old blob.",
          "fields": [
            {
              "name": "(whole blob)",
              "type": "bytes",
              "required": true,
              "description": "Same formats as above."
            }
          ],
          "example": "(protobuf) older ConversationStateStructure",
          "notes": [
            "Previous roots are still meaningful: UserMessage.conversation_state_blob_id points at them for rewind."
          ]
        },
        {
          "type": "blob: prompt message JSON / role=system",
          "concept": "system-message",
          "summary": "The system prompt sent to the model.",
          "when": "First entry of root_prompt_messages_json.",
          "fields": [
            {
              "name": "role",
              "type": "\"system\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "content",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"role\":\"system\",\"content\":\"You are an AI coding assistant.\"}"
        },
        {
          "type": "blob: prompt message JSON / role=user",
          "concept": "user-message",
          "summary": "A user-role model message: either injected context (<user_info>, <system_reminder>, <system_notification>, <timestamp> …) or the user's query wrapped in <user_query> tags.",
          "when": "Per user turn, plus context injections.",
          "fields": [
            {
              "name": "role",
              "type": "\"user\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "content",
              "type": "string | array of content parts",
              "required": true,
              "description": "String for the initial <user_info> context; array of text parts for queries."
            },
            {
              "name": "providerOptions.cursor.requestId",
              "type": "string (uuid)",
              "required": false,
              "description": "On query messages; equals AgentConversationTurnStructure.request_id."
            },
            {
              "name": "providerOptions.cursor.requestContextCompleteness",
              "type": "object<string,bool> {agentSkills, customSubagents, env, gitRepos, gitStatus, mcp, mcpFileSystem, repositoryInfo, rules}",
              "required": false,
              "description": "On the context message."
            },
            {
              "name": "providerOptions.cursor.isSummary",
              "type": "boolean",
              "required": false,
              "description": "true on compaction summary messages; JSONL writer skips them."
            }
          ],
          "example": "{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"<user_query>\\nExample prompt\\n</user_query>\"}],\"providerOptions\":{\"cursor\":{\"requestId\":\"00000000-0000-4000-8000-000000000002\"}}}"
        },
        {
          "type": "blob: prompt message JSON / role=assistant",
          "concept": "assistant-message",
          "summary": "One model response message: reasoning, text and tool calls.",
          "when": "Per model response (one per LLM call within a turn).",
          "fields": [
            {
              "name": "role",
              "type": "\"assistant\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Short per-request counter-like id (Values include 1-char strings); not globally unique."
            },
            {
              "name": "content",
              "type": "array of parts (redacted-reasoning | reasoning | text | tool-call)",
              "required": true,
              "description": "—"
            },
            {
              "name": "providerOptions.cursor.pendingToolCallStartedAtMs",
              "type": "number",
              "required": false,
              "description": "Values include on 3 messages."
            }
          ],
          "example": "{\"role\":\"assistant\",\"id\":\"1\",\"content\":[{\"type\":\"redacted-reasoning\",\"data\":\"ZXhhbXBsZQ==\",\"providerOptions\":{\"cursor\":{\"modelName\":\"example-model\"}}},{\"type\":\"text\",\"text\":\"Reading the file.\"},{\"type\":\"tool-call\",\"toolCallId\":\"tool_00000000-0000-4000-8000-000000000004\",\"toolName\":\"Read\",\"args\":{\"path\":\"src/example.ts\"}}]}"
        },
        {
          "type": "blob: prompt message JSON / role=tool",
          "concept": "tool-result",
          "summary": "The result of exactly one tool call as sent back to the model, plus the structured result as JSON.",
          "when": "After each tool call completes.",
          "fields": [
            {
              "name": "role",
              "type": "\"tool\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Equals the toolCallId (5,861/5,863)."
            },
            {
              "name": "content",
              "type": "array with one tool-result part",
              "required": true,
              "description": "—"
            },
            {
              "name": "providerOptions.cursor.highLevelToolCallResult",
              "type": "object {output: <camelCase JSON of the protobuf <Name>Result oneof, e.g. {success:{...}} | {failure:{...}} | {rejected:{...}} | {error:{...}}, plus isBackground, terminalsFolder, sandboxPolicy}, isError: bool, rawErrorMessages?: string[]}",
              "required": false,
              "description": "Structured result (same data as ToolCall.result in the step blob)."
            }
          ],
          "example": "{\"role\":\"tool\",\"id\":\"tool_00000000-0000-4000-8000-000000000004\",\"content\":[{\"type\":\"tool-result\",\"toolCallId\":\"tool_00000000-0000-4000-8000-000000000004\",\"toolName\":\"Read\",\"result\":\"1|export const example = 1;\",\"experimental_content\":[{\"type\":\"text\",\"text\":\"1|export const example = 1;\"}]}],\"providerOptions\":{\"cursor\":{\"highLevelToolCallResult\":{\"output\":{\"success\":{\"path\":\"src/example.ts\",\"totalLines\":1}},\"isError\":false}}}}"
        },
        {
          "type": "jsonl / role=user",
          "concept": "user-message",
          "summary": "A user prompt in the readable mirror.",
          "when": "Appended when the corresponding prompt-message JSON blob appears in the root.",
          "fields": [
            {
              "name": "role",
              "type": "\"user\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content[]",
              "type": "array of {type:'text', text}",
              "required": true,
              "description": "Single text part; context tags (user_info, rules, system_reminder, git_status, attached_files, …24 tags) are stripped; <user_query> wrapper is kept."
            }
          ],
          "example": "{\"role\":\"user\",\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"<user_query>\\nExample prompt\\n</user_query>\"}]}}",
          "notes": [
            "If the first two non-system messages are both user, the first (the <user_info> context) is dropped."
          ]
        },
        {
          "type": "jsonl / role=assistant",
          "concept": "assistant-message",
          "summary": "One assistant prompt message flattened: text (+thinking) then tool_use parts.",
          "when": "Appended per assistant prompt message.",
          "fields": [
            {
              "name": "role",
              "type": "\"assistant\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content[]",
              "type": "array of text | tool_use",
              "required": true,
              "description": "First part: text = visible text and thinking joined by blank line; redacted reasoning becomes the literal '[REDACTED]'; <think>/<thinking> tags removed. Then one {type:'tool_use', name, input} per tool call."
            }
          ],
          "example": "{\"role\":\"assistant\",\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"[REDACTED]\\n\\nReading the file.\"},{\"type\":\"tool_use\",\"name\":\"Read\",\"input\":{\"path\":\"src/example.ts\"}}]}}"
        },
        {
          "type": "jsonl / type=turn_ended",
          "concept": "turn-end",
          "summary": "Marks the end of an agent turn with its outcome.",
          "when": "After each agent run completes, errors or is aborted.",
          "persisted": "only survives only until the next full rewrite of the file; usually only the last turn's line remains",
          "fields": [
            {
              "name": "type",
              "type": "\"turn_ended\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "status",
              "type": "enum(success|error|aborted)",
              "required": true,
              "description": "—"
            },
            {
              "name": "error",
              "type": "string",
              "required": false,
              "description": "Present for error and (optionally) aborted."
            }
          ],
          "example": "{\"type\":\"turn_ended\",\"status\":\"success\"}"
        },
        {
          "type": "jsonl / type=metadata",
          "concept": "summary",
          "summary": "Optional first line with a generated overview of the transcript.",
          "when": "Only when the writer is given an overviewFactory (full write).",
          "persisted": "only not configured by the CLI writer; other hosts may emit it",
          "fields": [
            {
              "name": "type",
              "type": "\"metadata\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "metadata.overview",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"metadata\",\"metadata\":{\"overview\":\"Example overview\"}}"
        },
        {
          "type": "meta.json",
          "concept": "session-title",
          "summary": "Resume-picker sidecar for a chat.",
          "when": "On chat creation and whenever name or latestRootBlobId changes; backfilled from store.db if absent.",
          "persisted": "only written by newer builds",
          "fields": [
            {
              "name": "schemaVersion",
              "type": "1",
              "required": true,
              "description": "—"
            },
            {
              "name": "createdAtMs",
              "type": "number",
              "required": true,
              "description": "—"
            },
            {
              "name": "updatedAtMs",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "hasConversation",
              "type": "boolean",
              "required": true,
              "description": "latestRootBlobId non-empty."
            },
            {
              "name": "title",
              "type": "string",
              "required": false,
              "description": "Chat name (omitted for default)."
            },
            {
              "name": "isSubagent",
              "type": "true",
              "required": false,
              "description": "Present when meta.subagentInfo is set."
            },
            {
              "name": "cwd",
              "type": "string",
              "required": false,
              "description": "Absolute workspace path."
            }
          ],
          "example": "{\"schemaVersion\":1,\"createdAtMs\":1760000000000,\"hasConversation\":true,\"title\":\"Example chat\",\"updatedAtMs\":1760000300000,\"cwd\":\"/path/to/project\"}"
        },
        {
          "type": "prompt_history.json",
          "concept": "queue",
          "summary": "Per-chat input history (up-arrow).",
          "when": "When the user submits a prompt.",
          "persisted": "only chat had typed prompts in an interactive build ≥ June 2026",
          "fields": [
            {
              "name": "[]",
              "type": "array of string",
              "required": true,
              "description": "Newest first, de-duplicated after normalisation, max 500."
            }
          ],
          "example": "[\"Second prompt\",\"First prompt\"]",
          "notes": ["A global ~/.cursor/prompt_history.json from earlier builds may also exist."]
        }
      ],
      "contentBlocks": [
        {
          "type": "json part / text",
          "concept": "assistant-message",
          "summary": "Plain text in a user or assistant prompt message.",
          "fields": [
            {
              "name": "type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Hello\"}"
        },
        {
          "type": "json part / redacted-reasoning",
          "concept": "reasoning",
          "summary": "Provider-encrypted reasoning; content is not readable.",
          "when": "Assistant messages from reasoning models.",
          "fields": [
            {
              "name": "type",
              "type": "\"redacted-reasoning\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "string (opaque, base64-like)",
              "required": true,
              "description": "Opaque."
            },
            {
              "name": "providerOptions.cursor.modelName",
              "type": "string",
              "required": false,
              "description": "Model that produced it."
            }
          ],
          "example": "{\"type\":\"redacted-reasoning\",\"data\":\"ZXhhbXBsZQ==\",\"providerOptions\":{\"cursor\":{\"modelName\":\"example-model\"}}}"
        },
        {
          "type": "json part / reasoning",
          "concept": "reasoning",
          "summary": "Readable reasoning text.",
          "when": "Models that expose reasoning.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "type",
              "type": "\"reasoning\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"reasoning\",\"text\":\"Thinking about it\"}"
        },
        {
          "type": "json part / tool-call",
          "concept": "tool-call",
          "summary": "A tool invocation by the model.",
          "fields": [
            {
              "name": "type",
              "type": "\"tool-call\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "toolCallId",
              "type": "string",
              "required": true,
              "description": "'tool_<uuid>'."
            },
            {
              "name": "toolName",
              "type": "string",
              "required": true,
              "description": "Model-facing name: Read, StrReplace, Grep, Shell, Glob, Write, ReadLints, TodoWrite, SemanticSearch, Delete, WebFetch, AskQuestion, WebSearch, Task, ListMcpResources, Await, MCP tool names, … (may be null per aux)."
            },
            {
              "name": "args",
              "type": "object",
              "required": true,
              "description": "JSON arguments."
            }
          ],
          "example": "{\"type\":\"tool-call\",\"toolCallId\":\"tool_00000000-0000-4000-8000-000000000004\",\"toolName\":\"Grep\",\"args\":{\"pattern\":\"example\"}}"
        },
        {
          "type": "json part / tool-result",
          "concept": "tool-result",
          "summary": "Model-visible tool output.",
          "fields": [
            {
              "name": "type",
              "type": "\"tool-result\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "toolCallId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "toolName",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "result",
              "type": "string | object | number",
              "required": true,
              "description": "Usually string; objects for MCP results; a number once."
            },
            {
              "name": "experimental_content",
              "type": "array of {type:'text', text}",
              "required": false,
              "description": "Multi-part version of result (5,866/5,869)."
            }
          ],
          "example": "{\"type\":\"tool-result\",\"toolCallId\":\"tool_00000000-0000-4000-8000-000000000004\",\"toolName\":\"Grep\",\"result\":\"No matches\",\"experimental_content\":[{\"type\":\"text\",\"text\":\"No matches\"}]}"
        },
        {
          "type": "json part / image",
          "concept": "attachment",
          "summary": "Image attached to a user message.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "type",
              "type": "\"image\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "image",
              "type": "string | {__type:'Uint8Array', hex}",
              "required": false,
              "description": "Byte arrays are stored as {__type:'Uint8Array',hex} to bytes; field names follow the AI SDK CoreMessage shape."
            },
            {
              "name": "mimeType",
              "type": "string",
              "required": false,
              "description": "unknown"
            }
          ],
          "example": "{\"type\":\"image\",\"image\":{\"__type\":\"Uint8Array\",\"hex\":\"89504e47\"},\"mimeType\":\"image/png\"}",
          "notes": ["Field names other than `type` are not established."]
        },
        {
          "type": "json part / file",
          "concept": "attachment",
          "summary": "File attached to a message.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "type",
              "type": "\"file\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "filename",
              "type": "string",
              "required": false,
              "description": "Used by the writer."
            },
            {
              "name": "data / mimeType",
              "type": "unknown",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"file\",\"filename\":\"example.pdf\",\"mimeType\":\"application/pdf\",\"data\":{\"__type\":\"Uint8Array\",\"hex\":\"25504446\"}}"
        },
        {
          "type": "jsonl part / text",
          "concept": "assistant-message",
          "summary": "Text in a JSONL mirror line.",
          "fields": [
            {
              "name": "type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Hello\"}"
        },
        {
          "type": "jsonl part / tool_use",
          "concept": "tool-call",
          "summary": "Tool call in a JSONL mirror assistant line (no id, no result).",
          "fields": [
            {
              "name": "type",
              "type": "\"tool_use\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "object",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tool_use\",\"name\":\"Read\",\"input\":{\"path\":\"src/example.ts\"}}"
        }
      ],
      "linking": [
        {
          "topic": "ordering",
          "rule": "Do NOT order blobs by rowid or id. Start at meta.latestRootBlobId, decode ConversationStateStructure, and follow root_prompt_messages_json in array order for the model transcript, or turns[] -> user_message + steps[] in array order for the UI transcript. rowid changes on INSERT OR REPLACE."
        },
        {
          "topic": "message parent links",
          "rule": "There are no parent pointers between messages; order is positional within the root's lists. A turn links to its UserMessage and steps by 32-byte blob ids (bytes fields), hex-encode them to look up blobs.id."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "JSON: assistant part tool-call.toolCallId == tool message content[0].toolCallId == tool message id. Protobuf: ToolCall.tool_call_id; args and result are in the same ToolCall message. JSONL: no ids and no results."
        },
        {
          "topic": "turns",
          "rule": "Each ConversationTurnStructure is one user turn; its request_id matches the JSON user message providerOptions.cursor.requestId. JSONL marks turn end with type=turn_ended (often only the last)."
        },
        {
          "topic": "subagents",
          "rule": "Subagents share the parent's store.db. Walk root.subagent_states (inline) and root.subagent_state_refs (blob ids of SubagentPersistedState); each has its own ConversationStateStructure. Link to the parent call via subagent_runs_by_parent_tool_call_id / AgentConversationTurnStructure.subagent_dispatch_steps. JSONL mirrors go to agent-transcripts/<parent>/subagents/<id>.jsonl. A separate store with meta.subagentInfo {parentAgentId, rootParentAgentId, toolCallId, typeName} is also possible."
        },
        {
          "topic": "forks",
          "rule": "/fork copies every blob into a new chat folder (new uuid) in the same workspace, sets the same latestRootBlobId, name '<name> (forked)' and a new createdAt. No parent-chat id is recorded, so lineage can only be reconstructed from shared blob ids/roots."
        },
        {
          "topic": "compaction",
          "rule": "Compaction appends a ConversationSummaryArchive (summarized_messages blob ids + summary_message blob id + window_tail) to root.summary_archives and replaces the head of root_prompt_messages_json with a summary message flagged providerOptions.cursor.isSummary. Full history = concat(archives[].summarized_messages) + current root_prompt_messages_json minus system and isSummary messages (this is what the JSONL writer does)."
        },
        {
          "topic": "resume",
          "rule": "Resume opens the same store.db and reloads the root from latestRootBlobId; new turns append to the same lists and a new root is written."
        },
        {
          "topic": "branches/rewind",
          "rule": "Each UserMessage.conversation_state_blob_id is the root before that turn. Rewind sets the root back to that blob (conversation) and optionally restores files from file_states_v2 content/initial_content blob ids. Rewound-away blobs stay in the table as unreachable rows."
        },
        {
          "topic": "sidecar references",
          "rule": "File snapshots, read content and images are separate raw blobs referenced by 32-byte ids. Shell output files are referenced by path under ~/.cursor/projects/<slug>/terminals/. Subagent cloud transcripts by transcript_path strings."
        }
      ],
      "versioning": "No format version inside blobs or JSONL. Signals: SQLite PRAGMA user_version=1 (set on every open by this build); meta.json schemaVersion=1; the CLI build is not recorded per chat. Protobuf is forward/backward compatible by field number: older roots carry a removed field 2 (seen in 113 local roots) and lack newer fields (e.g. agent_type, subagent_state_refs). Meta mode 'auto-run' is a legacy value mapped to default+isRunEverything. Because the server authors all non-root blobs, the JSON message shape can change independently of the CLI version. JSONL tool names CallDynamicTool/CallMcpTool appear only in older mirrors.",
      "usage": [
        {
          "field": "root.token_details.used_tokens / max_tokens",
          "meaning": "Current context-window occupancy vs limit at the checkpoint; not cumulative and not billing."
        },
        {
          "field": "root.token_details.breakdown.categories[] {id,label,character_count,estimated_tokens}",
          "meaning": "Estimated per-category context breakdown (rules, tools, history …)."
        },
        {
          "field": "(not persisted) InteractionUpdate.turn_ended TurnEndedUpdate {input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens, ended_at_ms}",
          "meaning": "Per-turn token usage exists only on the live stream / hooks; it is not written to store.db or JSONL. No cost field anywhere."
        }
      ],
      "gotchas": [
        "Blob type is not stored. Decode by graph position from the root; a first-byte heuristic ('{' => JSON) misclassifies raw file snapshots that are JSON (package.json, tsconfig) and the aux 0x0a/0x12+0x20 reference scan can produce false references.",
        "Most rows are dead: every checkpoint writes a new root and never deletes the old one (≈9.4k of 28.8k local blobs are stale roots). Walking 'all blobs' double-counts messages.",
        "Two parallel transcripts live in one DB: root_prompt_messages_json (model context JSON, includes tool results and the system prompt) and turns (protobuf UI steps with structured args/results and timings). They are not 1:1 (one assistant JSON message per LLM call vs one step per text/thinking/tool segment).",
        "Blob ids in protobuf are raw 32-byte values; blobs.id is their lowercase hex. latestRootBlobId in meta is already hex.",
        "meta.value is hex-encoded JSON, not JSON.",
        "Open with WAL: copy store.db + -wal + -shm together, or open read-only with immutable=1 when -shm is missing; opening mode=ro without -shm fails ('unable to open database file').",
        "The JSONL mirror is not append-only: the writer rewrites the whole file after compaction, after a turn_ended write, or when the prefix changes (rewind), so older turn_ended lines disappear and lines can change.",
        "JSONL drops: system prompt, tool results, ids, timestamps, isSummary messages, the leading <user_info> message, and context tags inside user text; redacted reasoning is merged into the text part as '[REDACTED]'.",
        "Edit tool results embed full before/after file contents; read_paths and file_states_v2 keys are absolute user paths - treat the DB as sensitive.",
        "JSONL files can outlive their chat folder: deleting from the picker removes only ~/.cursor/chats/.../<chatId>.",
        "Forks copy every blob and record no parent id.",
        "Chats without a checkpoint have latestRootBlobId '' and may have no meta.json."
      ],
      "evidence": ["transcript-format-cursor-agent-2026-10-12-d47ca18-local"],
      "references": {}
    },
    {
      "harness": "opencode",
      "variant": "current",
      "default": true,
      "version": "2.1.4",
      "stability": "source-observed",
      "sourceRevision": "68bc26b7da1990ce10ffecfbc1e09eb13aa5d824",
      "container": "One SQLite database (`opencode.db`, WAL mode). Each transcript entry is a row in `session_message` whose `data` column holds JSON. Images and files are stored inline as base64 or `data:` URIs.",
      "discriminator": "`session_message.type`, then `data.status` for compaction rows, `data.content[].type` for assistant content and `state.status` for tool blocks.",
      "layout": [
        {
          "path": "~/.local/share/opencode/ (XDG_DATA_HOME/opencode, also on macOS)",
          "kind": "other",
          "description": "Global data root."
        },
        {
          "path": "~/.local/share/opencode/opencode.db (+ -wal, -shm)",
          "kind": "database",
          "description": "SQLite (WAL) shared by all projects: session_v2, session_message, session_inbox, instruction_*, event, event_sequence, kv, project, workspace, worktree, permission, credential, account*, migration, plus untouched 1.x tables (session, message, part, todo, session_share, ...) on upgraded installs. OPENCODE_DB overrides (relative to data dir; ':memory:' allowed); non-standard channels use opencode-<channel>.db unless OPENCODE_DISABLE_CHANNEL_DB."
        },
        {
          "path": "~/.local/share/opencode/opencode-next.db",
          "kind": "database",
          "description": "Pre-release 2.x database imported on first start if present."
        },
        {
          "path": "~/.local/share/opencode/tool-output/tool_<26-char id>[.<ext>]",
          "kind": "sidecar",
          "description": "Full text of tool results truncated to 2000 lines / 50 KiB (and saved binary outputs); referenced by tool state metadata.outputPath and the inline marker. Deleted after 7 days."
        },
        {
          "path": "~/.local/share/opencode/shell/<project-id>/<sh_id>.out",
          "kind": "sidecar",
          "description": "Combined stdout/stderr capture for shells (Shell.Info.file); retained 7 days."
        },
        {
          "path": "~/.local/share/opencode/snapshot/<project-id>/<hash(worktree)>/",
          "kind": "blob-store",
          "description": "Private git directory whose tree hashes are the snapshot ids in assistant.snapshot.start/end and revert.snapshot; diffs/reverts are computed from it."
        },
        {
          "path": "~/.local/share/opencode/storage/ (1.x remnant)",
          "kind": "other",
          "description": "Older JSON storage (migration marker, session_diff) from pre-SQLite builds; not read for 2.x transcripts. on a 1.x install."
        }
      ],
      "envelope": [
        {
          "name": "id",
          "type": "text",
          "required": true,
          "description": "msg_ + 12 hex time + 14 base62 (ascending). Event-derived rows reuse the event id suffix (evt_→msg_); fork copies use msg_<forkEventSuffix>_<seq>."
        },
        {
          "name": "session_id",
          "type": "text",
          "required": true,
          "description": "FK session_v2.id (cascade delete)."
        },
        {
          "name": "type",
          "type": "text",
          "required": true,
          "description": "Discriminator."
        },
        {
          "name": "seq",
          "type": "integer",
          "required": true,
          "description": "Durable event seq that inserted the row; unique per session; gaps are normal."
        },
        {
          "name": "time_created",
          "type": "integer ms",
          "required": true,
          "description": "Mirrors data.time.created (assistant: request start)."
        },
        {
          "name": "time_updated",
          "type": "integer ms",
          "required": true,
          "description": "Last mutation."
        },
        {
          "name": "data",
          "type": "json text",
          "required": true,
          "description": "—"
        }
      ],
      "records": [
        {
          "type": "session_v2 (row)",
          "concept": "session-header",
          "summary": "One row per session: identity, lineage, location, title, current agent/model, running usage totals and state timestamps.",
          "when": "Inserted on session.created (or session.forked); columns updated by later events.",
          "fields": [
            {
              "name": "id",
              "type": "text ses_<26>",
              "required": true,
              "description": "Descending time-sortable id (newest sorts first)."
            },
            {
              "name": "project_id",
              "type": "text",
              "required": true,
              "description": "FK project.id."
            },
            {
              "name": "workspace_id",
              "type": "text",
              "required": false,
              "description": "—"
            },
            {
              "name": "parent_id",
              "type": "text",
              "required": false,
              "description": "Parent session for subagent/child sessions."
            },
            {
              "name": "fork_session_id",
              "type": "text",
              "required": false,
              "description": "Source session of a fork (parent_id is null on forks)."
            },
            {
              "name": "fork_boundary",
              "type": "json {type:before|through, messageID}",
              "required": false,
              "description": "—"
            },
            {
              "name": "slug",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "directory",
              "type": "text",
              "required": true,
              "description": "Absolute working directory."
            },
            {
              "name": "path",
              "type": "text",
              "required": false,
              "description": "Subpath relative to project worktree."
            },
            {
              "name": "title",
              "type": "text",
              "required": false,
              "description": "Optional since the 2.x split (1.x required)."
            },
            {
              "name": "version",
              "type": "text",
              "required": true,
              "description": "opencode version that created the session."
            },
            {
              "name": "share_url",
              "type": "text",
              "required": false,
              "description": "Legacy/sharing."
            },
            {
              "name": "summary_additions/summary_deletions/summary_files",
              "type": "integer",
              "required": false,
              "description": "Legacy 1.x diff summary."
            },
            {
              "name": "summary_diffs",
              "type": "json FileDiff.LegacyInfo[]",
              "required": false,
              "description": "Legacy 1.x."
            },
            {
              "name": "metadata",
              "type": "json Record<string,Json>",
              "required": false,
              "description": "Host annotations; inherited by children/forks."
            },
            {
              "name": "cost",
              "type": "real",
              "required": true,
              "description": "USD total (steps + title + compaction usage)."
            },
            {
              "name": "tokens_input/tokens_output/tokens_reasoning/tokens_cache_read/tokens_cache_write",
              "type": "integer",
              "required": true,
              "description": "Running totals."
            },
            {
              "name": "revert",
              "type": "json Revert {messageID, partID?, snapshot?, files?} | RevertV1",
              "required": false,
              "description": "Staged (uncommitted) revert."
            },
            {
              "name": "permission",
              "type": "json Permission.Ruleset",
              "required": false,
              "description": "—"
            },
            {
              "name": "agent",
              "type": "text",
              "required": false,
              "description": "Current agent id."
            },
            {
              "name": "model",
              "type": "json {id, providerID, variant?}",
              "required": false,
              "description": "Current model."
            },
            {
              "name": "time_created/time_updated",
              "type": "integer ms",
              "required": true,
              "description": "—"
            },
            {
              "name": "time_idle",
              "type": "integer ms",
              "required": false,
              "description": "Last terminal execution."
            },
            {
              "name": "idle_outcome",
              "type": "text succeeded|failed|interrupted",
              "required": false,
              "description": "—"
            },
            {
              "name": "time_viewed",
              "type": "integer ms",
              "required": false,
              "description": "Read watermark."
            },
            {
              "name": "time_compacting",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "time_archived",
              "type": "integer",
              "required": false,
              "description": "—"
            },
            {
              "name": "time_suspended",
              "type": "integer",
              "required": false,
              "description": "Execution claim timestamp (historical name)."
            },
            {
              "name": "resume_attempts",
              "type": "integer",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"id\":\"ses_8f3a2b1c0d9eAbCdEfGhIjKlMn\",\"project_id\":\"prj_example\",\"parent_id\":null,\"slug\":\"quiet-river\",\"directory\":\"/home/user/project\",\"title\":\"Example\",\"version\":\"2.1.4\",\"cost\":0.0123,\"tokens_input\":1200,\"tokens_output\":300,\"tokens_reasoning\":0,\"tokens_cache_read\":0,\"tokens_cache_write\":0,\"agent\":\"build\",\"model\":{\"id\":\"example-model\",\"providerID\":\"example\"},\"time_created\":1767261600000,\"time_updated\":1767261660000}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/session/sql.ts#L23-L78"
        },
        {
          "type": "session_message / user",
          "concept": "user-message",
          "summary": "A user prompt with optional inline file attachments, @agent and skill mentions.",
          "when": "Projected when a queued/steered inbox item of type user is delivered (session.inbox.delivered).",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.files",
              "type": "FileAttachment[] {data(base64), mime, source:{type:inline}|{type:uri,uri}, name?, description?, mention?{start,end,text}}",
              "required": false,
              "description": "Attachment bytes are stored inline as base64."
            },
            {
              "name": "data.agents",
              "type": "{name, mention?}[]",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.skills",
              "type": "{id, name, text?, mention?}[]",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"id\":\"msg_0a1b2c3d4e5fAbCdEfGhIjKlMn\",\"session_id\":\"ses_x\",\"type\":\"user\",\"seq\":4,\"time_created\":1767261601000,\"time_updated\":1767261601000,\"data\":{\"text\":\"Hello\",\"time\":{\"created\":1767261601000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L76-L84"
        },
        {
          "type": "session_message / synthetic",
          "concept": "system-message",
          "summary": "Host-injected user-role text (e.g. subagent completion notices, plugin input), not typed by the user.",
          "when": "session.synthetic events or delivered synthetic inbox items.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.text",
              "type": "string",
              "required": true,
              "description": "Model-facing text."
            },
            {
              "name": "data.description",
              "type": "string",
              "required": false,
              "description": "Short display summary."
            }
          ],
          "example": "{\"type\":\"synthetic\",\"seq\":9,\"data\":{\"text\":\"<subagent sessionID=\\\"ses_y\\\" state=\\\"completed\\\" description=\\\"scan\\\">done</subagent>\",\"description\":\"scan\",\"metadata\":{\"source\":\"subagent\",\"childID\":\"ses_y\",\"agent\":\"explore\",\"state\":\"completed\"},\"time\":{\"created\":1767261700000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L86-L92"
        },
        {
          "type": "session_message / system",
          "concept": "system-message",
          "summary": "Chronological instruction update shown to the model (e.g. AGENTS.md/instructions changed), frozen at emit time.",
          "when": "session.instructions.updated with rendered text (initial baseline has no text and produces no row). Also the V1 migration's tool-rename notice.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.description",
              "type": "string",
              "required": false,
              "description": "e.g. 'Instructions updated: <keys>'"
            },
            {
              "name": "data.metadata.notice",
              "type": "\"instructions\"",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.metadata.instructionSources",
              "type": "string[]",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"system\",\"seq\":2,\"data\":{\"text\":\"<instructions>...</instructions>\",\"description\":\"Instructions updated: project/agents.md\",\"metadata\":{\"notice\":\"instructions\",\"instructionSources\":[\"project/agents.md\"]},\"time\":{\"created\":1767261600100}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L94-L102"
        },
        {
          "type": "session_message / skill",
          "concept": "attachment",
          "summary": "A skill was activated and its text injected.",
          "when": "session.skill.activated.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.skill",
              "type": "string (Skill.ID)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.text",
              "type": "string",
              "required": true,
              "description": "Injected skill body."
            }
          ],
          "example": "{\"type\":\"skill\",\"seq\":5,\"data\":{\"skill\":\"skill_example\",\"name\":\"example\",\"text\":\"# Example skill\",\"time\":{\"created\":1767261602000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L104-L111"
        },
        {
          "type": "session_message / shell",
          "concept": "tool-call",
          "summary": "A user-run shell command (! in the TUI) with status and final output page.",
          "when": "Inserted on session.shell.started (status running); updated in place on session.shell.ended.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata.background",
              "type": "boolean",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.shellID",
              "type": "string sh_<26>",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.command",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.status",
              "type": "enum(running,exited,timeout,killed)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.exit",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.output",
              "type": "{output, cursor, size, truncated}",
              "required": false,
              "description": "Final page; full capture is in the shell output file."
            },
            {
              "name": "data.time.created",
              "type": "number ms",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.time.completed",
              "type": "number ms",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"shell\",\"seq\":12,\"data\":{\"shellID\":\"sh_0a1b2c3d4e5fAbCdEfGhIjKlMn\",\"command\":\"ls\",\"status\":\"exited\",\"exit\":0,\"output\":{\"output\":\"README.md\\n\",\"cursor\":10,\"size\":10,\"truncated\":false},\"time\":{\"created\":1767261800000,\"completed\":1767261800200}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L113-L126"
        },
        {
          "type": "session_message / assistant",
          "concept": "assistant-message",
          "summary": "One model step (one LLM request): ordered text/reasoning/tool content, model, finish reason, per-step usage, workspace snapshots, error and retry state.",
          "when": "Inserted on session.step.started; mutated in place by text/reasoning/tool/retry/step.streamed/step.ended/step.failed events. A retry of the same step reuses the row (fields reset).",
          "fields": [
            {
              "name": "data.agent",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.model",
              "type": "{id, providerID, variant?}",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.content",
              "type": "(text|reasoning|tool)[]",
              "required": true,
              "description": "See contentBlocks."
            },
            {
              "name": "data.snapshot",
              "type": "{start?, end?, files?:string[]}",
              "required": false,
              "description": "Git tree hashes in the snapshot repo before/after the step; files changed."
            },
            {
              "name": "data.finish",
              "type": "enum(stop,length,tool-calls,content-filter,error,unknown)",
              "required": false,
              "description": "Absent while running."
            },
            {
              "name": "data.rawFinish",
              "type": "string",
              "required": false,
              "description": "Provider-native finish."
            },
            {
              "name": "data.native",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Step-level provider replay data (was providerState before 2.1)."
            },
            {
              "name": "data.cost",
              "type": "number USD",
              "required": false,
              "description": "Set at step end."
            },
            {
              "name": "data.tokens",
              "type": "{input, output, reasoning, cache:{read, write}} (all numbers; no total field)",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.error",
              "type": "{type:string, message:string, status?:100-599, response?:{body}, retryAfterMs?:int}",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.retry",
              "type": "{attempt, at(ms), error}",
              "required": false,
              "description": "Pending retry; cleared when the step restarts or the turn idles."
            },
            {
              "name": "data.metadata",
              "type": "Record",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.time.created",
              "type": "number ms",
              "required": true,
              "description": "Request dispatch time."
            },
            {
              "name": "data.time.streamed",
              "type": "number ms",
              "required": false,
              "description": "Provider body ended."
            },
            {
              "name": "data.time.completed",
              "type": "number ms",
              "required": false,
              "description": "Absent = still running or crashed."
            }
          ],
          "example": "{\"type\":\"assistant\",\"seq\":6,\"data\":{\"agent\":\"build\",\"model\":{\"id\":\"example-model\",\"providerID\":\"example\"},\"content\":[{\"type\":\"text\",\"text\":\"Hi!\"}],\"finish\":\"stop\",\"cost\":0.0004,\"tokens\":{\"input\":100,\"output\":5,\"reasoning\":0,\"cache\":{\"read\":0,\"write\":0}},\"time\":{\"created\":1767261602000,\"streamed\":1767261603000,\"completed\":1767261603000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L213-L239"
        },
        {
          "type": "session_message / compaction (running)",
          "concept": "compaction",
          "summary": "Compaction in progress placeholder.",
          "when": "session.compaction.started (row id = inbox inputID or msg_ from event).",
          "persisted": "only transient; left behind if the process dies",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.status",
              "type": "\"running\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.reason",
              "type": "enum(auto,manual)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.summary",
              "type": "string",
              "required": true,
              "description": "Empty while running."
            }
          ],
          "example": "{\"type\":\"compaction\",\"seq\":30,\"data\":{\"status\":\"running\",\"reason\":\"auto\",\"summary\":\"\",\"time\":{\"created\":1767262000000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L249-L255"
        },
        {
          "type": "session_message / compaction (completed)",
          "concept": "compaction",
          "summary": "Context checkpoint: history before this row is replaced by the summary (or provider-native window).",
          "when": "session.compaction.ended updates the running row (or appends one).",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.status",
              "type": "\"completed\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.reason",
              "type": "enum(auto,manual)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.model",
              "type": "{id, providerID, variant?}",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.summary",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.native",
              "type": "Record; native.messages = provider compaction window",
              "required": false,
              "description": "Was providerContext before 2.1."
            },
            {
              "name": "data.cost",
              "type": "number",
              "required": false,
              "description": "Compaction request cost."
            },
            {
              "name": "data.tokens",
              "type": "{input, output, reasoning, cache:{read, write}} (all numbers; no total field)",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.metadata.keepID",
              "type": "msg id",
              "required": false,
              "description": "First message kept verbatim after the summary (rows between keepID and this row)."
            },
            {
              "name": "data.metadata.recent",
              "type": "string",
              "required": false,
              "description": "Pre-2.1 / V1-migrated kept text (was top-level recent)."
            }
          ],
          "example": "{\"type\":\"compaction\",\"seq\":30,\"data\":{\"status\":\"completed\",\"reason\":\"auto\",\"summary\":\"Goal: ...\",\"cost\":0.002,\"tokens\":{\"input\":9000,\"output\":400,\"reasoning\":0,\"cache\":{\"read\":0,\"write\":0}},\"metadata\":{\"keepID\":\"msg_0a1b2c3d4e5fAbCdEfGhIjKlMp\"},\"time\":{\"created\":1767262000000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L257-L267"
        },
        {
          "type": "session_message / compaction (failed)",
          "concept": "compaction",
          "summary": "Compaction attempt that failed.",
          "when": "session.compaction.failed.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.status",
              "type": "\"failed\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.reason",
              "type": "enum(auto,manual)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.error",
              "type": "{type:string, message:string, status?:100-599, response?:{body}, retryAfterMs?:int}",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.cost",
              "type": "number",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.tokens",
              "type": "{input, output, reasoning, cache:{read, write}} (all numbers; no total field)",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"compaction\",\"seq\":31,\"data\":{\"status\":\"failed\",\"reason\":\"manual\",\"error\":{\"type\":\"provider\",\"message\":\"overloaded\"},\"time\":{\"created\":1767262000000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L269-L276"
        },
        {
          "type": "session_message / idle",
          "concept": "turn-end",
          "summary": "Turn boundary: the session went idle; every step since the previous idle belongs to one turn.",
          "when": "session.execution.succeeded/failed/interrupted (not for interrupted reason=shutdown, which resumes the same turn).",
          "persisted": "always (per completed turn)",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.outcome",
              "type": "enum(succeeded,failed,interrupted)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.error",
              "type": "{type:string, message:string, status?:100-599, response?:{body}, retryAfterMs?:int}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"idle\",\"seq\":7,\"data\":{\"outcome\":\"succeeded\",\"time\":{\"created\":1767261603100}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L284-L295"
        },
        {
          "type": "session_message / agent-switched",
          "concept": "session-settings",
          "summary": "Agent changed.",
          "when": "session.agent.selected.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.agent",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.previous",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"agent-switched\",\"seq\":1,\"data\":{\"agent\":\"plan\",\"previous\":\"build\",\"time\":{\"created\":1767261600050}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L46-L52"
        },
        {
          "type": "session_message / model-switched",
          "concept": "session-settings",
          "summary": "Model changed.",
          "when": "session.model.selected.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.model",
              "type": "{id, providerID, variant?}",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.previous",
              "type": "{id, providerID, variant?}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"model-switched\",\"seq\":3,\"data\":{\"model\":{\"id\":\"example-model\",\"providerID\":\"example\"},\"time\":{\"created\":1767261600060}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L54-L60"
        },
        {
          "type": "session_message / location-switched",
          "concept": "session-settings",
          "summary": "Session moved to another directory/workspace/project.",
          "when": "session.moved (also updates session_v2 location columns).",
          "persisted": "conditional",
          "fields": [
            {
              "name": "data.metadata",
              "type": "Record<string,unknown>",
              "required": false,
              "description": "Free-form metadata (event metadata, e.g. notice/source tags)."
            },
            {
              "name": "data.time.created",
              "type": "number (epoch ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.location",
              "type": "{directory, workspaceID?}",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.projectID",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.subpath",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "data.previous",
              "type": "{location, projectID?, subpath?}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"location-switched\",\"seq\":20,\"data\":{\"location\":{\"directory\":\"/home/user/other\"},\"time\":{\"created\":1767261900000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L62-L74"
        },
        {
          "type": "session_inbox (row)",
          "concept": "queue",
          "summary": "Queued or steering input admitted but not yet delivered to the transcript (user, synthetic, compaction request, move).",
          "when": "session.inbox.enqueued inserts; delivered/cancelled deletes; delivery.changed flips steer/queue. Revert deletes rows with enqueued_seq >= boundary.",
          "persisted": "only transient",
          "fields": [
            {
              "name": "id",
              "type": "text msg_",
              "required": true,
              "description": "Becomes the session_message id on delivery."
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "type",
              "type": "enum(user,synthetic,compaction,move)",
              "required": true,
              "description": "—"
            },
            {
              "name": "payload",
              "type": "json UserPayload|SyntheticPayload|{}|MovePayload",
              "required": true,
              "description": "—"
            },
            {
              "name": "delivery",
              "type": "enum(steer,queue)",
              "required": true,
              "description": "—"
            },
            {
              "name": "enqueued_seq",
              "type": "integer",
              "required": true,
              "description": "Event seq at admission."
            },
            {
              "name": "time_created",
              "type": "integer ms",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"id\":\"msg_0a1b2c3d4e5fAbCdEfGhIjKlMq\",\"session_id\":\"ses_x\",\"type\":\"user\",\"payload\":{\"text\":\"also check tests\"},\"delivery\":\"queue\",\"enqueued_seq\":15,\"time_created\":1767261650000}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/session/sql.ts#L126-L146"
        },
        {
          "type": "instruction_entry / instruction_state / instruction_blob (rows)",
          "concept": "system-message",
          "summary": "Per-session instruction state: API-managed key/value entries, the current and epoch-initial instruction key→hash maps, and content-addressed instruction bodies.",
          "when": "instructions.updated, forks, compaction epochs, revert rewinds.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "instruction_entry.(session_id,key)",
              "type": "pk",
              "required": true,
              "description": "—"
            },
            {
              "name": "instruction_entry.value",
              "type": "json",
              "required": false,
              "description": "<=256 KiB"
            },
            {
              "name": "instruction_entry.removed",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "instruction_state.epoch_start/through_seq",
              "type": "integer",
              "required": true,
              "description": "—"
            },
            {
              "name": "instruction_state.initial_values/current_values",
              "type": "json Record<key,sha256>",
              "required": true,
              "description": "—"
            },
            {
              "name": "instruction_blob.hash",
              "type": "text sha256 hex",
              "required": true,
              "description": "—"
            },
            {
              "name": "instruction_blob.value",
              "type": "json",
              "required": false,
              "description": "Instruction body."
            }
          ],
          "example": "{\"session_id\":\"ses_x\",\"epoch_start\":0,\"through_seq\":2,\"initial_values\":{\"project/agents.md\":\"aaaaaaaa...\"},\"current_values\":{\"project/agents.md\":\"aaaaaaaa...\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/session/sql.ts#L148-L177"
        },
        {
          "type": "event (row)",
          "concept": "metadata-other",
          "summary": "Durable event log (event-sourcing input for the projections above), stored as type '<event>.<version>' with per-aggregate seq.",
          "when": "Only when the server runs with events.persist=true (set by the Cloudflare workerd host). The CLI does not set it, so locally the table stays empty and only event_sequence advances.",
          "persisted": "only events.persist only",
          "fields": [
            {
              "name": "id",
              "type": "text evt_<26>",
              "required": true,
              "description": "—"
            },
            {
              "name": "aggregate_id",
              "type": "text (session id)",
              "required": true,
              "description": "—"
            },
            {
              "name": "seq",
              "type": "integer",
              "required": true,
              "description": "—"
            },
            {
              "name": "created",
              "type": "integer ms",
              "required": true,
              "description": "—"
            },
            {
              "name": "type",
              "type": "text e.g. session.tool.success.2",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "json",
              "required": true,
              "description": "Event payload."
            }
          ],
          "example": "{\"id\":\"evt_0a1b2c3d4e5fAbCdEfGhIjKlMn\",\"aggregate_id\":\"ses_x\",\"seq\":6,\"created\":1767261602000,\"type\":\"session.step.started.1\",\"data\":{\"sessionID\":\"ses_x\",\"assistantMessageID\":\"msg_y\",\"agent\":\"build\",\"model\":{\"id\":\"m\",\"providerID\":\"p\"},\"started\":1767261602000}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/event/sql.ts#L10-L26",
          "notes": [
            "Durable event types (52 definitions; ephemeral deltas/progress never stored): session.created, agent.selected, model.selected, moved, renamed, metadata.updated, permissions, viewed, archived, unarchived, deleted(v2), forked(v2), inbox.delivered, inbox.enqueued, inbox.cancelled, inbox.delivery.changed, execution.started/succeeded/failed/interrupted, instructions.updated(v2), synthetic, skill.activated, shell.started/ended, step.started/streamed/ended/failed, text.started/ended, reasoning.started/ended, tool.input.started/ended, tool.called, tool.success(v2), tool.failed(v2), retry.scheduled, compaction.started/ended/failed, revert.staged/cleared/committed, usage.recorded (internal), message.content.updated (replay-only), worktree.resolved",
            "Ephemeral (never persisted): session.usage.updated, text.delta, reasoning.delta, tool.input.delta, tool.progress, compaction.delta."
          ]
        },
        {
          "type": "event_sequence (row)",
          "concept": "metadata-other",
          "summary": "Last committed event seq per aggregate (session); session_message.seq values come from it.",
          "when": "Every durable event commit.",
          "fields": [
            {
              "name": "aggregate_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "seq",
              "type": "integer",
              "required": true,
              "description": "—"
            },
            {
              "name": "owner_id",
              "type": "text",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"aggregate_id\":\"ses_x\",\"seq\":42,\"owner_id\":null}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/event/sql.ts#L4-L8"
        },
        {
          "type": "kv (row)",
          "concept": "metadata-other",
          "summary": "Key/value state; key migration.v1-v2 records the in-place 1.x to 2.x import.",
          "when": "Migration and misc.",
          "persisted": "conditional",
          "fields": [
            {
              "name": "key",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "value",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "time_created/time_updated",
              "type": "integer",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"key\":\"migration.v1-v2\",\"value\":\"{...}\",\"time_created\":1767261600000,\"time_updated\":1767261600000}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/database/v1-migration.bun.ts#L220"
        },
        {
          "type": "legacy message (1.x row)",
          "concept": "assistant-message",
          "summary": "1.x message row (role user|assistant) left in the old `message` table after upgrade; the 2.x reader ignores it once imported.",
          "when": "Written by 1.x only; remains after the V1→V2 import (tables are not dropped).",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text msg_",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "FK legacy session table."
            },
            {
              "name": "time_created/time_updated",
              "type": "integer",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.role",
              "type": "enum(user,assistant)",
              "required": true,
              "description": "—"
            },
            {
              "name": "data (user)",
              "type": "{time.created, format?, summary?{title?,body?,diffs}, agent, model{providerID,modelID,variant?}, system?, tools?}",
              "required": false,
              "description": "—"
            },
            {
              "name": "data (assistant)",
              "type": "{time{created,completed?}, error?{name,data}, parentID, modelID, providerID, mode, agent, path{cwd,root}, summary?, cost, tokens{total?,input,output,reasoning,cache{read,write}}, structured?, variant?, finish?}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"id\":\"msg_x\",\"session_id\":\"ses_x\",\"data\":{\"role\":\"assistant\",\"parentID\":\"msg_u\",\"modelID\":\"m\",\"providerID\":\"p\",\"mode\":\"build\",\"agent\":\"build\",\"path\":{\"cwd\":\"/p\",\"root\":\"/p\"},\"cost\":0,\"tokens\":{\"input\":1,\"output\":1,\"reasoning\":0,\"cache\":{\"read\":0,\"write\":0}},\"time\":{\"created\":1767261600000}}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L332-L488"
        }
      ],
      "contentBlocks": [
        {
          "type": "assistant.content / text",
          "concept": "assistant-message",
          "summary": "Assistant visible text segment.",
          "when": "session.text.started pushes empty text; text.ended fills it.",
          "fields": [
            {
              "name": "type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "native",
              "type": "Record",
              "required": false,
              "description": "Provider replay data (was state before 2.1)."
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Done.\"}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L178-L183"
        },
        {
          "type": "assistant.content / reasoning",
          "concept": "reasoning",
          "summary": "Model reasoning segment.",
          "when": "reasoning.started/ended.",
          "fields": [
            {
              "name": "type",
              "type": "\"reasoning\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "native",
              "type": "Record",
              "required": false,
              "description": "Encrypted/signature data."
            },
            {
              "name": "time",
              "type": "{created, completed?}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"reasoning\",\"text\":\"Check the config first.\",\"time\":{\"created\":1767261602100,\"completed\":1767261602500}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L185-L194"
        },
        {
          "type": "assistant.content / tool",
          "concept": "tool-call",
          "summary": "A tool call and its result live in one block whose state advances streaming → running → completed | error.",
          "when": "tool.input.started creates it; input.ended, called, success/failed update it.",
          "fields": [
            {
              "name": "type",
              "type": "\"tool\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Provider call id."
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "e.g. shell, read, edit, write, patch, glob, grep, subagent, skill, todo, question, webfetch, websearch, mcp tools."
            },
            {
              "name": "executed",
              "type": "boolean",
              "required": false,
              "description": "true when OpenCode ran it (false for provider-executed tools)."
            },
            {
              "name": "native",
              "type": "Record",
              "required": false,
              "description": "Call native data merged with result native data."
            },
            {
              "name": "state",
              "type": "ToolState",
              "required": true,
              "description": "See tool state entries."
            },
            {
              "name": "time",
              "type": "{created, ran?, completed?}",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"tool\",\"id\":\"call_1\",\"name\":\"shell\",\"executed\":true,\"state\":{\"status\":\"completed\",\"input\":{\"command\":\"ls\"},\"content\":[{\"type\":\"text\",\"text\":\"README.md\"}],\"metadata\":{\"truncated\":false}},\"time\":{\"created\":1767261602600,\"ran\":1767261602700,\"completed\":1767261602900}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L163-L176"
        },
        {
          "type": "tool.state / streaming",
          "concept": "tool-call",
          "summary": "Arguments are still streaming (1.x called this pending).",
          "when": "session.tool.input.started; input.ended sets the raw string.",
          "persisted": "only only if interrupted mid-stream",
          "fields": [
            {
              "name": "status",
              "type": "\"streaming\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "string",
              "required": true,
              "description": "Raw argument text."
            }
          ],
          "example": "{\"status\":\"streaming\",\"input\":\"{\\\"command\\\":\\\"l\"}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L128-L132"
        },
        {
          "type": "tool.state / running",
          "concept": "tool-progress",
          "summary": "Parsed input, executing.",
          "when": "session.tool.called.",
          "persisted": "only in-flight or crashed",
          "fields": [
            {
              "name": "status",
              "type": "\"running\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "metadata",
              "type": "Record<string,Json>",
              "required": true,
              "description": "Progress metadata is ephemeral; stored value is {} unless later terminal."
            }
          ],
          "example": "{\"status\":\"running\",\"input\":{\"command\":\"ls\"},\"metadata\":{}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L134-L139"
        },
        {
          "type": "tool.state / completed",
          "concept": "tool-result",
          "summary": "Successful result.",
          "when": "session.tool.success (v2).",
          "fields": [
            {
              "name": "status",
              "type": "\"completed\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "object",
              "required": true,
              "description": "—"
            },
            {
              "name": "content",
              "type": "non-empty (text|file)[]",
              "required": true,
              "description": "Model-facing result."
            },
            {
              "name": "metadata",
              "type": "Record<string,Json>",
              "required": false,
              "description": "UI metadata; truncated:boolean and outputPath when output was spilled to tool-output/."
            }
          ],
          "example": "{\"status\":\"completed\",\"input\":{\"path\":\"a.txt\"},\"content\":[{\"type\":\"text\",\"text\":\"hello\"}],\"metadata\":{\"truncated\":false}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L141-L147"
        },
        {
          "type": "tool.state / error",
          "concept": "tool-result",
          "summary": "Failed or interrupted tool.",
          "when": "session.tool.failed (v2).",
          "fields": [
            {
              "name": "status",
              "type": "\"error\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "input",
              "type": "object",
              "required": true,
              "description": "{} if failure happened while streaming."
            },
            {
              "name": "error",
              "type": "{type:string, message:string, status?:100-599, response?:{body}, retryAfterMs?:int}",
              "required": true,
              "description": "e.g. type tool.execution, tool.interrupted (V1 import)."
            },
            {
              "name": "content",
              "type": "(text|file)[]",
              "required": false,
              "description": "Partial output."
            },
            {
              "name": "metadata",
              "type": "Record",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"status\":\"error\",\"input\":{\"command\":\"false\"},\"error\":{\"type\":\"tool.execution\",\"message\":\"exit 1\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/session-message.ts#L149-L156"
        },
        {
          "type": "tool.content / text",
          "concept": "tool-result",
          "summary": "Text item in a tool result.",
          "when": "Inside state.content.",
          "fields": [
            {
              "name": "type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"ok\"}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/tool.ts#L65-L69"
        },
        {
          "type": "tool.content / file",
          "concept": "attachment",
          "summary": "File/media item in a tool result, by URI.",
          "when": "Inside state.content.",
          "fields": [
            {
              "name": "type",
              "type": "\"file\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "uri",
              "type": "string",
              "required": true,
              "description": "data: URI or other URI."
            },
            {
              "name": "mime",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"file\",\"uri\":\"data:image/png;base64,iVBORw0KGgo=\",\"mime\":\"image/png\"}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/tool.ts#L71-L77"
        },
        {
          "type": "user.files[]",
          "concept": "attachment",
          "summary": "Prompt attachment stored inline.",
          "when": "user message data.files.",
          "fields": [
            {
              "name": "data",
              "type": "base64",
              "required": true,
              "description": "—"
            },
            {
              "name": "mime",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "source",
              "type": "{type:inline}|{type:uri,uri}",
              "required": true,
              "description": "—"
            },
            {
              "name": "name",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "description",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "mention",
              "type": "{start,end,text}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"data\":\"aGVsbG8=\",\"mime\":\"text/plain\",\"source\":{\"type\":\"inline\"},\"name\":\"a.txt\"}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/prompt.ts#L26-L34"
        },
        {
          "type": "user.agents[] / user.skills[]",
          "concept": "attachment",
          "summary": "@agent and skill mentions in the prompt.",
          "when": "user message data.agents / data.skills.",
          "fields": [
            {
              "name": "agents[].name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "skills[].id/name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "skills[].text",
              "type": "string",
              "required": false,
              "description": "—"
            },
            {
              "name": "*.mention",
              "type": "{start,end,text}",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"name\":\"explore\",\"mention\":{\"start\":0,\"end\":8,\"text\":\"@explore\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/prompt.ts#L50-L62"
        },
        {
          "type": "legacy part / text",
          "concept": "assistant-message",
          "summary": "1.x `part` row of type text (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{text, synthetic?, ignored?, time?{start,end?}, metadata?}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"text\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L87-L116"
        },
        {
          "type": "legacy part / reasoning",
          "concept": "reasoning",
          "summary": "1.x `part` row of type reasoning (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"reasoning\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{text, metadata?, time{start,end?}}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"reasoning\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L118-L127"
        },
        {
          "type": "legacy part / file",
          "concept": "attachment",
          "summary": "1.x `part` row of type file (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"file\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{mime, filename?, url (data: or file:), source?{type:file|symbol|resource,...}}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"file\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L171-L178"
        },
        {
          "type": "legacy part / tool",
          "concept": "tool-call",
          "summary": "1.x `part` row of type tool (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"tool\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{callID, tool, state:{status:pending{input,raw}|running{input,title?,metadata?,time.start}|completed{input,output,title,metadata,time{start,end,compacted?},attachments?}|error{input,error,metadata?,time}}, metadata?}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"tool\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L259-L330",
          "notes": [
            "Import mapping: text/reasoning/tool → assistant content; user text/file/agent → user fields; synthetic text → synthetic row; compaction+summary assistant → compaction row; step-start/snapshot/patch/step-finish → assistant.snapshot; subtask and its task tool call dropped; tool renames bash→shell, task→subagent, apply_patch→patch; pending/running tools become error tool.interrupted."
          ]
        },
        {
          "type": "legacy part / step-start",
          "concept": "turn-start",
          "summary": "1.x `part` row of type step-start (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"step-start\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{snapshot?}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"step-start\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L233-L238"
        },
        {
          "type": "legacy part / step-finish",
          "concept": "token-usage",
          "summary": "1.x `part` row of type step-finish (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"step-finish\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{reason, snapshot?, cost, tokens{total?,input,output,reasoning,cache{read,write}}}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"step-finish\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L240-L257"
        },
        {
          "type": "legacy part / snapshot",
          "concept": "workspace-state",
          "summary": "1.x `part` row of type snapshot (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"snapshot\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{snapshot}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"snapshot\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L87-L91"
        },
        {
          "type": "legacy part / patch",
          "concept": "workspace-state",
          "summary": "1.x `part` row of type patch (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"patch\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{hash, files[]}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"patch\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L94-L100"
        },
        {
          "type": "legacy part / agent",
          "concept": "attachment",
          "summary": "1.x `part` row of type agent (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"agent\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{name, source?{value,start,end}}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"agent\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L181-L193"
        },
        {
          "type": "legacy part / subtask",
          "concept": "session-lineage",
          "summary": "1.x `part` row of type subtask (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"subtask\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{prompt, description, agent, model?{providerID,modelID}, command?}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"subtask\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L204-L218"
        },
        {
          "type": "legacy part / retry",
          "concept": "error",
          "summary": "1.x `part` row of type retry (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"retry\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{attempt, error(APIError), time{created}}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"retry\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L220-L231"
        },
        {
          "type": "legacy part / compaction",
          "concept": "compaction",
          "summary": "1.x `part` row of type compaction (legacy table; migrated into 2.x shapes on first 2.x start).",
          "when": "Written by 1.x only.",
          "until": "2.0.0",
          "persisted": "legacy (1.x databases only)",
          "fields": [
            {
              "name": "id",
              "type": "text prt_",
              "required": true,
              "description": "—"
            },
            {
              "name": "message_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "session_id",
              "type": "text",
              "required": true,
              "description": "—"
            },
            {
              "name": "data.type",
              "type": "\"compaction\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "object",
              "required": true,
              "description": "{auto, overflow?, tail_start_id?}"
            }
          ],
          "example": "{\"id\": \"prt_x\", \"message_id\": \"msg_x\", \"session_id\": \"ses_x\", \"data\": {\"type\": \"compaction\"}}",
          "reference": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/schema/src/v1/session.ts#L195-L202"
        }
      ],
      "linking": [
        {
          "topic": "ordering",
          "rule": "ORDER BY seq within session_id. seq is the per-session durable event sequence, so it has gaps; do not use id or time_created as the primary order (assistant time_created is reset on retry)."
        },
        {
          "topic": "message parent links",
          "rule": "None in 2.x: the transcript is a flat seq-ordered list (1.x assistant.parentID pointed at the user message; it is not carried over)."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "Call and result are the same assistant content block (type tool, keyed by id); the result is state.content when status=completed/error. Find the latest block with matching id in the step."
        },
        {
          "topic": "turns",
          "rule": "A turn = rows after the previous idle row up to and including the next idle row (steered prompts mid-turn included). Each assistant row is one LLM step; finish=tool-calls means another step follows."
        },
        {
          "topic": "subagents",
          "rule": "The subagent tool creates a child session_v2 row with parent_id = parent session; the tool result text/metadata carries the child sessionID; background completions arrive in the parent as synthetic rows with metadata {source:subagent, childID, agent, state}."
        },
        {
          "topic": "forks",
          "rule": "A fork is a new session_v2 row with parent_id NULL, fork_session_id = source and fork_boundary {before|through, messageID}; settled rows up to the boundary are physically copied with new ids msg_<evt>_<seq> and the same seq; compaction metadata.keepID is remapped."
        },
        {
          "topic": "compaction",
          "rule": "Model history starts at the latest completed compaction row (status=completed): summary replaces everything before it; rows from metadata.keepID up to the compaction are re-rendered as 'recent' text; a provider-native compaction (native.messages) replays only on the same model. Raw rows before the compaction remain in the table."
        },
        {
          "topic": "branches/rewind",
          "rule": "Revert: session_v2.revert holds a staged revert (messageID, snapshot, files); on commit all session_message rows with seq >= the target row's seq (and inbox rows) are DELETED and instruction state rewound. No branches are kept."
        },
        {
          "topic": "resume",
          "rule": "Resume continues the same session id; an assistant row with no time.completed is an interrupted/in-flight step and is superseded by the next step.started."
        },
        {
          "topic": "sidecar references",
          "rule": "tool state.metadata.outputPath → tool-output file; shell rows → shell/<project>/<sh_id>.out; assistant.snapshot.start/end and session_v2.revert.snapshot → git trees in snapshot/<project>/<hash>/."
        },
        {
          "topic": "session settings",
          "rule": "Current agent/model are session_v2.agent/model; history of changes is the agent-switched/model-switched rows; each assistant row records the agent and model it used."
        }
      ],
      "versioning": "No per-row schema version. session_v2.version records the creating opencode version; the `migration` table lists applied migration ids (seeded from __drizzle_migrations on old installs); kv migration.v1-v2 records the 1.x import. Readers upgrade older 2.x row shapes on decode (SessionLegacy): before 2.1 native data was named state/providerState/resultState/providerResultState, compaction stored kept text in `recent` and provider windows in `providerContext`; window media before 2.0.15 used {mediaType,data}. 1.x (session/message/part tables, role+parts model) is imported in place on first 2.x start into session_v2/session_message; the 1.x tables and rows are left behind, and persisted 1.x events are deleted. A pre-split 2.x DB (marker 20260730195856_optional_session_title) had its `session` table renamed to session_v2 in migration 20260804233008_loose_psylocke.",
      "usage": [
        {
          "field": "assistant data.tokens {input, output, reasoning, cache.read, cache.write}",
          "meaning": "Per-step usage from step.ended (or step.failed when reported). No total; reasoning is a separate bucket."
        },
        {
          "field": "assistant data.cost",
          "meaning": "Per-step USD computed by OpenCode."
        },
        {
          "field": "compaction data.cost/tokens",
          "meaning": "Cost of the compaction request (accounted via internal usage.recorded)."
        },
        {
          "field": "session_v2.cost and tokens_*",
          "meaning": "Running totals = all step usage + title-generation usage + compaction usage. Title usage appears in no transcript row, so summing rows undercounts."
        }
      ],
      "gotchas": [
        "Rows are mutable: assistant, shell and compaction rows are rewritten in place while streaming; read time.completed / status before trusting content.",
        "Tool calls and results are one block; there is no separate tool_result row.",
        "seq has gaps and equals the event sequence; forks reuse parent seq values.",
        "Revert physically deletes rows; there is no history of abandoned branches.",
        "The event table is empty on local CLI installs (events.persist is only set by the Cloudflare host); do not rely on it for history.",
        "Upgraded 1.x databases still contain the old session/message/part tables; reading them gives stale pre-import data and misses all 2.x activity.",
        "session_pending is defined in the schema but unused at 2.1.4.",
        "A failed provider step and its retry reuse the same assistant row id; fields are reset on restart.",
        "Older 2.x rows use legacy key names (providerState, state, recent, providerContext); apply the SessionLegacy renames before decoding.",
        "Large tool output is truncated in the DB and the full text lives in tool-output/ files that are deleted after 7 days.",
        "User attachments are stored as base64 in the row and can make rows large."
      ],
      "evidence": [
        "transcript-format-opencode-packages-cli-src-database-path-ts",
        "transcript-format-opencode-packages-cli-src-server-process-ts",
        "transcript-format-opencode-packages-core-src-bus-ts",
        "transcript-format-opencode-packages-core-src-database-database-ts",
        "transcript-format-opencode-packages-core-src-database-v1-migration-bun-ts",
        "transcript-format-opencode-packages-core-src-event-sql-ts",
        "transcript-format-opencode-packages-core-src-kv-sql-ts",
        "transcript-format-opencode-packages-core-src-session-history-ts",
        "transcript-format-opencode-packages-core-src-session-inbox-ts",
        "transcript-format-opencode-packages-core-src-session-message-updater-ts",
        "transcript-format-opencode-packages-core-src-session-projector-ts",
        "transcript-format-opencode-packages-core-src-session-sql-ts",
        "transcript-format-opencode-packages-core-src-session-subagent-completion-ts",
        "transcript-format-opencode-packages-core-src-shell-ts",
        "transcript-format-opencode-packages-core-src-snapshot-ts",
        "transcript-format-opencode-packages-core-src-tool-output-ts",
        "transcript-format-opencode-packages-core-src-tool-plugin-subagent-ts",
        "transcript-format-opencode-packages-schema-src-instruction-ts",
        "transcript-format-opencode-packages-schema-src-prompt-ts",
        "transcript-format-opencode-packages-schema-src-session-inbox-ts",
        "transcript-format-opencode-packages-schema-src-session-message-ts",
        "transcript-format-opencode-packages-schema-src-shell-ts",
        "transcript-format-opencode-packages-schema-src-tool-ts",
        "transcript-format-opencode-packages-schema-src-v1-session-ts",
        "transcript-format-opencode-packages-server-src-workerd-ts",
        "transcript-format-opencode-packages-util-src-global-roots-ts"
      ],
      "references": {
        "location": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/util/src/global-roots.ts#L4-L18",
        "records": "https://github.com/anomalyco/opencode/blob/68bc26b7da1990ce10ffecfbc1e09eb13aa5d824/packages/core/src/session/sql.ts#L23-L78"
      }
    },
    {
      "harness": "pi",
      "variant": "current",
      "default": true,
      "version": "1.4.0",
      "stability": "documented-public",
      "sourceRevision": "4a080252f06caf63a525d7873c5d94d3c23887e0",
      "container": "JSON Lines, one entry per line, appended as the session runs and uncompressed. The file is rewritten only when an older format version is migrated or a branch is extracted.",
      "discriminator": "`type`, then `message.role` for `message` entries.",
      "layout": [
        {
          "path": "~/.pi/agent/",
          "kind": "other",
          "description": "Agent directory (PI_CODING_AGENT_DIR overrides). Also holds settings.json, auth.json, models.json, prompts/, tools/, mcp.json, pi-debug.log — none session-scoped."
        },
        {
          "path": "~/.pi/agent/sessions/--<cwd with leading separator removed and / \\ : replaced by ->--/",
          "kind": "other",
          "description": "One directory per working directory. A custom --session-dir / PI_CODING_AGENT_SESSION_DIR / sessionDir setting is flat and filtered by header cwd."
        },
        {
          "path": "~/.pi/agent/sessions/--<cwd>--/<ISO timestamp with : and . replaced by ->_<session-id>.jsonl",
          "kind": "transcript",
          "description": "The entire session: header line plus append-only tree of entries, including all branches. Not created until the first user/assistant message (since 0.99.0; first assistant before)."
        },
        {
          "path": "<os.tmpdir()>/pi-bash-<16 hex>.log",
          "kind": "sidecar",
          "description": "Full output of a truncated bash tool call or ! command, referenced by details.fullOutputPath / bashExecution.fullOutputPath. Temporary; not under the session dir and may be gone."
        }
      ],
      "envelope": [
        {
          "name": "type",
          "type": "string",
          "required": true,
          "description": "Entry type."
        },
        {
          "name": "id",
          "type": "string",
          "required": true,
          "description": "8 lowercase hex chars (first 8 of a random UUID, collision-checked); falls back to a full UUID. Absent on the session header (which uses the session id)."
        },
        {
          "name": "parentId",
          "type": "string|null",
          "required": true,
          "description": "Parent entry id; null for a root. Absent on the header."
        },
        {
          "name": "timestamp",
          "type": "string (ISO 8601)",
          "required": true,
          "description": "Entry write time. Distinct from message.timestamp (Unix ms)."
        }
      ],
      "records": [
        {
          "type": "session",
          "concept": "session-header",
          "summary": "First line of every file: format version, session id, start time and working directory; not part of the entry tree.",
          "when": "Built in memory by newSession()/createBranchedSession()/forkFrom(); written to disk together with all buffered entries when the first user or assistant message entry is appended (forkFrom writes it immediately).",
          "fields": [
            {
              "name": "type",
              "type": "\"session\"",
              "required": true,
              "description": "Discriminator."
            },
            {
              "name": "version",
              "type": "number",
              "required": false,
              "description": "Format version; absent means 1. Current is 3."
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Session id. UUIDv7 by default (since 0.67.1; UUIDv4 before); may be a caller-supplied id matching ^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$ via --session-id/SDK."
            },
            {
              "name": "timestamp",
              "type": "string (ISO 8601)",
              "required": true,
              "description": "Creation time; also used (with : and . replaced by -) as the file-name prefix."
            },
            {
              "name": "cwd",
              "type": "string",
              "required": true,
              "description": "Absolute working directory. Readers tolerate it missing/non-string on very old files (treated as empty)."
            },
            {
              "name": "parentSession",
              "type": "string",
              "required": false,
              "description": "Absolute path of the source session file for /fork, /clone, forkFrom() or newSession({parentSession})."
            }
          ],
          "example": "{\"type\":\"session\",\"version\":3,\"id\":\"01890a5d-ac96-774b-bcce-b302099a8057\",\"timestamp\":\"2026-01-01T10:00:00.000Z\",\"cwd\":\"/home/user/project\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L43-L50"
        },
        {
          "type": "message",
          "concept": "metadata-other",
          "summary": "Wrapper entry holding one AgentMessage; the role-specific payloads are listed below as message / <role>.",
          "when": "On every agent message_end for roles system, user, assistant, toolResult and custom (custom is re-routed to custom_message); bashExecution messages are appended after a ! command (deferred until agent_end if a turn is streaming).",
          "fields": [
            {
              "name": "type",
              "type": "\"message\"",
              "required": true,
              "description": "Discriminator."
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Entry id (8 hex chars)."
            },
            {
              "name": "parentId",
              "type": "string|null",
              "required": true,
              "description": "Parent entry id."
            },
            {
              "name": "timestamp",
              "type": "string (ISO 8601)",
              "required": true,
              "description": "Append time."
            },
            {
              "name": "message",
              "type": "AgentMessage",
              "required": true,
              "description": "Discriminated by message.role."
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"a1b2c3d4\",\"parentId\":\"f0e1d2c3\",\"timestamp\":\"2026-01-01T10:00:01.000Z\",\"message\":{\"role\":\"user\",\"content\":\"Hello\",\"timestamp\":1767261601000}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L64-L67"
        },
        {
          "type": "message / system",
          "concept": "system-message",
          "summary": "System prompt and tool loadout declaration (first request) or a delta that patches named prompt sections and adds/removes tools.",
          "when": "First model request of a session persists a leading system message with every section and full tool declarations; later prompt/tool changes persist delta system messages. Sessions from before 0.86.0 have none; the first request after upgrade declares the current prompt as a later system message.",
          "since": "0.86.0",
          "persisted": "only since 0.86.0",
          "fields": [
            {
              "name": "message.role",
              "type": "\"system\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content",
              "type": "string | TextContent[]",
              "required": true,
              "description": "Base prompt on the leading message; extra instructions on later ones (often empty string)."
            },
            {
              "name": "message.sections",
              "type": "Record<string, string|null>",
              "required": false,
              "description": "Named, ordered prompt sections; later messages replace by name, null removes."
            },
            {
              "name": "message.toolsAdded",
              "type": "Tool[] ({name, description, parameters (JSON Schema), constrainedSampling?})",
              "required": false,
              "description": "Complete tool definitions becoming available."
            },
            {
              "name": "message.toolsRemoved",
              "type": "{name}[]",
              "required": false,
              "description": "Tools that stop being available."
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"0a1b2c3d\",\"parentId\":null,\"timestamp\":\"2026-01-01T10:00:00.500Z\",\"message\":{\"role\":\"system\",\"content\":\"\",\"sections\":{\"preamble\":\"You are a coding assistant.\",\"cwd\":\"/project\"},\"toolsAdded\":[{\"name\":\"read\",\"description\":\"Read a file\",\"parameters\":{\"type\":\"object\",\"properties\":{}}}],\"timestamp\":1767261600500}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L554-L570",
          "notes": [
            "Replay every system message on the active path in order to reconstruct the current prompt and tools; there is no separate prompt-state entry.",
            "Inside a compacted context, system messages in the kept range are dropped in favour of compaction.systemMessage."
          ]
        },
        {
          "type": "message / user",
          "concept": "user-message",
          "summary": "A user prompt (typed, queued steering/follow-up, or SDK-sent).",
          "when": "message_end of the user message at the start of each prompt.",
          "fields": [
            {
              "name": "message.role",
              "type": "\"user\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content",
              "type": "string | (TextContent|ImageContent)[]",
              "required": true,
              "description": "Plain string or blocks; images are inline base64."
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"a1b2c3d4\",\"parentId\":\"0a1b2c3d\",\"timestamp\":\"2026-01-01T10:00:01.000Z\",\"message\":{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Hello\"}],\"timestamp\":1767261601000}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L572-L576"
        },
        {
          "type": "message / assistant",
          "concept": "assistant-message",
          "summary": "One completed model response: text, thinking and tool calls plus model identity, usage and stop reason.",
          "when": "message_end of each model response (one per LLM call; a tool-using turn yields several). Streaming partials (stopReason pending) are never persisted; errored and aborted responses are.",
          "fields": [
            {
              "name": "message.role",
              "type": "\"assistant\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content",
              "type": "(TextContent|ThinkingContent|ToolCall)[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.api",
              "type": "string",
              "required": true,
              "description": "Wire API, e.g. anthropic-messages, openai-responses, openai-completions, openai-codex-responses, azure-openai-responses, mistral-conversations, bedrock-converse-stream, google-generative-ai, google-vertex, pi-messages, or custom."
            },
            {
              "name": "message.provider",
              "type": "string",
              "required": true,
              "description": "Provider id."
            },
            {
              "name": "message.model",
              "type": "string",
              "required": true,
              "description": "Requested (physical) model id."
            },
            {
              "name": "message.responseModel",
              "type": "string",
              "required": false,
              "description": "Concrete provider model when it differs."
            },
            {
              "name": "message.responseId",
              "type": "string",
              "required": false,
              "description": "Provider response id."
            },
            {
              "name": "message.providerThinkingLevel",
              "type": "string",
              "required": false,
              "description": "Provider-native effort actually used."
            },
            {
              "name": "message.thinkingLevel",
              "type": "enum(off,minimal,low,medium,high,xhigh,max)",
              "required": false,
              "description": "Pi thinking level requested."
            },
            {
              "name": "message.diagnostics",
              "type": "{type,timestamp,error?{name?,message,stack?,code?},details?}[]",
              "required": false,
              "description": "Redacted provider/runtime diagnostics, e.g. provider_transport_failure, bedrock_response_failure, pi_messages_response_failure.",
              "since": "0.73.0"
            },
            {
              "name": "message.usage",
              "type": "Usage",
              "required": true,
              "description": "Usage object: input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost{input,output,cacheRead,cacheWrite,total}"
            },
            {
              "name": "message.stopReason",
              "type": "enum(stop,length,toolUse,error,aborted,deferred)",
              "required": true,
              "description": "pending exists in the type but is not persisted."
            },
            {
              "name": "message.deferred",
              "type": "DeferredHandle {provider,modelId,api,id,expiresAt?,pollAfterMs?,data?}",
              "required": false,
              "description": "Handle to retrieve a deferred response.",
              "since": "0.84.0"
            },
            {
              "name": "message.errorMessage",
              "type": "string",
              "required": false,
              "description": "Error text when stopReason is error/aborted."
            },
            {
              "name": "message.rawStopReason",
              "type": "string",
              "required": false,
              "description": "Provider-native stop reason."
            },
            {
              "name": "message.endTurn",
              "type": "boolean",
              "required": false,
              "description": "Provider explicit end-of-turn signal (Codex).",
              "since": "0.84.2"
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "Request start time."
            },
            {
              "name": "message.durationMs",
              "type": "number",
              "required": false,
              "description": "Monotonic duration of the response.",
              "since": "1.1.0"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"b2c3d4e5\",\"parentId\":\"a1b2c3d4\",\"timestamp\":\"2026-01-01T10:00:03.000Z\",\"message\":{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Hi!\"}],\"api\":\"anthropic-messages\",\"provider\":\"anthropic\",\"model\":\"example-model\",\"usage\":{\"input\":10,\"output\":3,\"cacheRead\":0,\"cacheWrite\":0,\"totalTokens\":13,\"cost\":{\"input\":0.00003,\"output\":0.00004,\"cacheRead\":0,\"cacheWrite\":0,\"total\":0.00007}},\"stopReason\":\"stop\",\"timestamp\":1767261602000,\"durationMs\":900}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L578-L608"
        },
        {
          "type": "message / toolResult",
          "concept": "tool-result",
          "summary": "Result of one tool call, linked to the call by toolCallId.",
          "when": "After a tool finishes; for parallel batches all results are appended after the batch completes, in the assistant's tool-call order.",
          "fields": [
            {
              "name": "message.role",
              "type": "\"toolResult\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.toolCallId",
              "type": "string",
              "required": true,
              "description": "ToolCall.id of the originating block."
            },
            {
              "name": "message.toolName",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content",
              "type": "(TextContent|ImageContent)[]",
              "required": true,
              "description": "What the model sees."
            },
            {
              "name": "message.details",
              "type": "JSON",
              "required": false,
              "description": "Tool-specific UI/metadata, not sent to model. Built-ins: bash {truncation?, fullOutputPath?}; read {truncation?}; edit {diff, patch, firstChangedLine?}; ls {truncation?, entryLimitReached?}; find {truncation?, resultLimitReached?}; grep {truncation?, matchLimitReached?, linesTruncated?}."
            },
            {
              "name": "message.usage",
              "type": "Usage",
              "required": false,
              "description": "Nested model work done by the tool; counted in session totals but not main-call accounting."
            },
            {
              "name": "message.nestedCalls",
              "type": "{calls:{id,name,arguments?,argumentsBytes?,status(ok|error|unfinished),durationMs?,error?}[], complete:boolean}",
              "required": false,
              "description": "Bounded record of tool-to-tool calls (e.g. codemode)."
            },
            {
              "name": "message.isError",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.durationMs",
              "type": "number",
              "required": false,
              "description": "Tool execution time.",
              "since": "1.1.0"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"c3d4e5f6\",\"parentId\":\"b2c3d4e5\",\"timestamp\":\"2026-01-01T10:00:04.000Z\",\"message\":{\"role\":\"toolResult\",\"toolCallId\":\"call_1\",\"toolName\":\"bash\",\"content\":[{\"type\":\"text\",\"text\":\"ok\"}],\"isError\":false,\"timestamp\":1767261604000}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L633-L650"
        },
        {
          "type": "message / bashExecution",
          "concept": "tool-call",
          "summary": "A user-initiated shell command (! or !! prefix, or RPC bash) with its output; not an LLM tool call.",
          "when": "After the command finishes; if a turn is streaming it is queued and appended at agent_end.",
          "persisted": "only user runs a shell command",
          "fields": [
            {
              "name": "message.role",
              "type": "\"bashExecution\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.command",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.output",
              "type": "string",
              "required": true,
              "description": "Possibly truncated output."
            },
            {
              "name": "message.exitCode",
              "type": "number|undefined",
              "required": true,
              "description": "Omitted from JSON when undefined."
            },
            {
              "name": "message.cancelled",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.truncated",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.fullOutputPath",
              "type": "string",
              "required": false,
              "description": "Temp file with full output (os.tmpdir()/pi-bash-<16hex>.log)."
            },
            {
              "name": "message.excludeFromContext",
              "type": "boolean",
              "required": false,
              "description": "true for !! commands: not converted into model context."
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"d4e5f6a7\",\"parentId\":\"c3d4e5f6\",\"timestamp\":\"2026-01-01T10:01:00.000Z\",\"message\":{\"role\":\"bashExecution\",\"command\":\"ls\",\"output\":\"README.md\",\"exitCode\":0,\"cancelled\":false,\"truncated\":false,\"timestamp\":1767261660000}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/messages.ts#L29-L40",
          "notes": ["Converted to user-role text for the model unless excludeFromContext."]
        },
        {
          "type": "message / custom",
          "concept": "system-message",
          "summary": "Legacy/alternate location for an extension context message; the agent re-routes role custom to a custom_message entry, so this appears only from SDK appendMessage() or v2 hookMessage migration.",
          "when": "Rare: direct SessionManager.appendMessage() with a CustomMessage, or v1/v2 files whose hookMessage role is renamed on load.",
          "persisted": "only SDK/legacy",
          "fields": [
            {
              "name": "message.role",
              "type": "\"custom\" (was \"hookMessage\" before v3)",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.customType",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.content",
              "type": "string | (TextContent|ImageContent)[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.display",
              "type": "boolean",
              "required": true,
              "description": "—"
            },
            {
              "name": "message.details",
              "type": "any",
              "required": false,
              "description": "—"
            },
            {
              "name": "message.timestamp",
              "type": "number (ms)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"message\",\"id\":\"e5f6a7b8\",\"parentId\":\"d4e5f6a7\",\"timestamp\":\"2026-01-01T10:02:00.000Z\",\"message\":{\"role\":\"custom\",\"customType\":\"my-ext\",\"content\":\"note\",\"display\":true,\"timestamp\":1767261720000}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/messages.ts#L46-L53"
        },
        {
          "type": "model_change",
          "concept": "session-settings",
          "summary": "User or runtime switched the selected model (may be a virtual model).",
          "when": "Session start (SDK records initial model/thinking), /model, model cycling, fallback switching.",
          "fields": [
            {
              "name": "provider",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "modelId",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"model_change\",\"id\":\"f6a7b8c9\",\"parentId\":\"e5f6a7b8\",\"timestamp\":\"2026-01-01T10:03:00.000Z\",\"provider\":\"openai\",\"modelId\":\"example-model\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L74-L78"
        },
        {
          "type": "thinking_level_change",
          "concept": "session-settings",
          "summary": "Thinking/reasoning level changed.",
          "when": "Session start and whenever the level changes.",
          "fields": [
            {
              "name": "thinkingLevel",
              "type": "string (off|minimal|low|medium|high|xhigh|max)",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"thinking_level_change\",\"id\":\"a7b8c9d0\",\"parentId\":\"f6a7b8c9\",\"timestamp\":\"2026-01-01T10:03:01.000Z\",\"thinkingLevel\":\"high\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L69-L72"
        },
        {
          "type": "usage",
          "concept": "token-usage",
          "summary": "Model-attributed usage that is not an assistant message (e.g. prompt-cache warming).",
          "when": "Cache warmer refreshes (kind cache_warm); any caller of appendUsage(). Not part of LLM context; hidden from the tree.",
          "since": "0.86.0",
          "persisted": "only cache warming or extension",
          "fields": [
            {
              "name": "kind",
              "type": "string",
              "required": true,
              "description": "Open-ended category; treat unknown kinds as normal usage."
            },
            {
              "name": "provider",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "model",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "usage",
              "type": "Usage",
              "required": true,
              "description": "Usage object: input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost{input,output,cacheRead,cacheWrite,total}"
            },
            {
              "name": "note",
              "type": "string",
              "required": false,
              "description": "Human-readable qualifier."
            }
          ],
          "example": "{\"type\":\"usage\",\"id\":\"b8c9d0e1\",\"parentId\":\"a7b8c9d0\",\"timestamp\":\"2026-01-01T10:04:00.000Z\",\"kind\":\"cache_warm\",\"provider\":\"anthropic\",\"model\":\"example-model\",\"usage\":{\"input\":0,\"output\":1,\"cacheRead\":50000,\"cacheWrite\":0,\"totalTokens\":50001,\"cost\":{\"input\":0,\"output\":0.00001,\"cacheRead\":0.015,\"cacheWrite\":0,\"total\":0.01501}}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L80-L89"
        },
        {
          "type": "compaction",
          "concept": "compaction",
          "summary": "Context compaction checkpoint: summary of earlier entries, the first kept entry, and the full system prompt/tool state at that point.",
          "when": "Manual /compact, auto-compaction on threshold or overflow, or extension-driven compaction.",
          "persisted": "only compaction runs",
          "fields": [
            {
              "name": "summary",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "firstKeptEntryId",
              "type": "string",
              "required": true,
              "description": "First retained entry before the compaction; equals the compaction's own id for retain-none (since 0.87.0)."
            },
            {
              "name": "tokensBefore",
              "type": "number",
              "required": true,
              "description": "Context tokens before compaction."
            },
            {
              "name": "details",
              "type": "any",
              "required": false,
              "description": "Default: {readFiles:string[], modifiedFiles:string[]}; extensions may store anything."
            },
            {
              "name": "usage",
              "type": "Usage",
              "required": false,
              "description": "Cost of producing the summary; counted in session totals."
            },
            {
              "name": "fromHook",
              "type": "boolean",
              "required": false,
              "description": "true when an extension produced it."
            },
            {
              "name": "systemMessage",
              "type": "SystemMessage",
              "required": false,
              "description": "Complete prompt/tool checkpoint; becomes the leading system message of compacted context.",
              "since": "0.86.0"
            }
          ],
          "example": "{\"type\":\"compaction\",\"id\":\"c9d0e1f2\",\"parentId\":\"b8c9d0e1\",\"timestamp\":\"2026-01-01T11:00:00.000Z\",\"summary\":\"Goal: ...\",\"firstKeptEntryId\":\"a1b2c3d4\",\"tokensBefore\":120000,\"details\":{\"readFiles\":[],\"modifiedFiles\":[]}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L91-L104",
          "notes": [
            "v1 files stored firstKeptEntryIndex (array index); migration converts it to firstKeptEntryId."
          ]
        },
        {
          "type": "branch_summary",
          "concept": "summary",
          "summary": "LLM summary of an abandoned branch, written when navigating /tree to another point with summarisation.",
          "when": "branchWithSummary(): parentId is the branch point (or null for a new root); fromId is the old leaf.",
          "persisted": "only tree navigation with summary",
          "fields": [
            {
              "name": "fromId",
              "type": "string",
              "required": true,
              "description": "Previous leaf whose path was summarised; literal \"root\" if there was no leaf."
            },
            {
              "name": "summary",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "details",
              "type": "any",
              "required": false,
              "description": "Default {readFiles, modifiedFiles}."
            },
            {
              "name": "usage",
              "type": "Usage",
              "required": false,
              "description": "—"
            },
            {
              "name": "fromHook",
              "type": "boolean",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"branch_summary\",\"id\":\"d0e1f2a3\",\"parentId\":\"a1b2c3d4\",\"timestamp\":\"2026-01-01T11:05:00.000Z\",\"fromId\":\"c9d0e1f2\",\"summary\":\"Tried approach A ...\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L106-L117"
        },
        {
          "type": "custom",
          "concept": "metadata-other",
          "summary": "Extension state that never enters model context.",
          "when": "appendCustomEntry() by extensions; built-in uses: pi.virtual-model-state {provider, modelId, state}, pi.bug-report {id, createdAt, hint, sessionIncluded, summaryIncluded, delivery, path?}.",
          "persisted": "only extensions",
          "fields": [
            {
              "name": "customType",
              "type": "string",
              "required": true,
              "description": "Extension identifier."
            },
            {
              "name": "data",
              "type": "any",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"custom\",\"id\":\"e1f2a3b4\",\"parentId\":\"d0e1f2a3\",\"timestamp\":\"2026-01-01T11:06:00.000Z\",\"customType\":\"my-extension\",\"data\":{\"count\":1}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L128-L132"
        },
        {
          "type": "custom_message",
          "concept": "system-message",
          "summary": "Extension-injected message that does enter model context (as user-role content).",
          "when": "pi.sendMessage() and other extension message injection (agent message_end with role custom).",
          "persisted": "only extensions",
          "fields": [
            {
              "name": "customType",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "content",
              "type": "string | (TextContent|ImageContent)[]",
              "required": true,
              "description": "—"
            },
            {
              "name": "display",
              "type": "boolean",
              "required": true,
              "description": "Render in TUI or hide."
            },
            {
              "name": "details",
              "type": "any",
              "required": false,
              "description": "Not sent to model."
            }
          ],
          "example": "{\"type\":\"custom_message\",\"id\":\"f2a3b4c5\",\"parentId\":\"e1f2a3b4\",\"timestamp\":\"2026-01-01T11:07:00.000Z\",\"customType\":\"my-extension\",\"content\":\"Injected context\",\"display\":true}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L159-L165"
        },
        {
          "type": "context_edit",
          "concept": "metadata-other",
          "summary": "Append-only edit that omits or replaces one earlier entry's content in future model context, without changing raw history.",
          "when": "appendContextEdit(); used by extensions and by error recovery, which omits a failed assistant attempt and its tool results (replacement null).",
          "since": "0.87.0",
          "persisted": "only edits/recovery",
          "fields": [
            {
              "name": "targetId",
              "type": "string",
              "required": true,
              "description": "A user/assistant/toolResult message entry or custom_message entry on the active branch."
            },
            {
              "name": "replacement",
              "type": "{content: string|block[]} | null",
              "required": true,
              "description": "null omits; string content for assistant/toolResult is normalized to one text block."
            }
          ],
          "example": "{\"type\":\"context_edit\",\"id\":\"a3b4c5d6\",\"parentId\":\"f2a3b4c5\",\"timestamp\":\"2026-01-01T11:08:00.000Z\",\"targetId\":\"b2c3d4e5\",\"replacement\":null}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L168-L180"
        },
        {
          "type": "label",
          "concept": "metadata-other",
          "summary": "User bookmark on an entry (set or clear).",
          "when": "/tree label action (l), extensions, branch-summary labelling; createBranchedSession re-emits resolved labels at the end of the new file.",
          "since": "0.31.0",
          "persisted": "only labelling",
          "fields": [
            {
              "name": "targetId",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "label",
              "type": "string|undefined",
              "required": true,
              "description": "Omitted from JSON (undefined) or empty to clear."
            }
          ],
          "example": "{\"type\":\"label\",\"id\":\"b4c5d6e7\",\"parentId\":\"a3b4c5d6\",\"timestamp\":\"2026-01-01T11:09:00.000Z\",\"targetId\":\"a1b2c3d4\",\"label\":\"checkpoint-1\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L135-L139"
        },
        {
          "type": "session_info",
          "concept": "session-title",
          "summary": "Session display name.",
          "when": "/name, --name/-n, pi.setSessionName(); latest entry in the file wins, empty name clears.",
          "persisted": "only naming",
          "fields": [
            {
              "name": "name",
              "type": "string",
              "required": false,
              "description": "Newlines collapsed to spaces, trimmed."
            }
          ],
          "example": "{\"type\":\"session_info\",\"id\":\"c5d6e7f8\",\"parentId\":\"b4c5d6e7\",\"timestamp\":\"2026-01-01T11:10:00.000Z\",\"name\":\"Refactor auth module\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L142-L145"
        }
      ],
      "contentBlocks": [
        {
          "type": "text",
          "concept": "assistant-message",
          "summary": "Plain text (user, assistant, toolResult, system, custom content).",
          "when": "Inside message.content arrays.",
          "fields": [
            {
              "name": "type",
              "type": "\"text\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "text",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "textSignature",
              "type": "string",
              "required": false,
              "description": "Opaque provider metadata (legacy id string or JSON {v:1,id,phase?:commentary|final_answer} for OpenAI Responses)."
            }
          ],
          "example": "{\"type\":\"text\",\"text\":\"Hello\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L422-L426"
        },
        {
          "type": "image",
          "concept": "attachment",
          "summary": "Inline base64 image (user, toolResult, custom content).",
          "when": "Inside content arrays.",
          "fields": [
            {
              "name": "type",
              "type": "\"image\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "data",
              "type": "string (base64)",
              "required": true,
              "description": "—"
            },
            {
              "name": "mimeType",
              "type": "string",
              "required": true,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"image\",\"data\":\"iVBORw0KGgo=\",\"mimeType\":\"image/png\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L438-L442"
        },
        {
          "type": "thinking",
          "concept": "reasoning",
          "summary": "Model reasoning (assistant only).",
          "when": "Inside assistant content.",
          "fields": [
            {
              "name": "type",
              "type": "\"thinking\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "thinking",
              "type": "string",
              "required": true,
              "description": "May be empty when redacted."
            },
            {
              "name": "thinkingSignature",
              "type": "string",
              "required": false,
              "description": "Opaque replay data / encrypted payload."
            },
            {
              "name": "redacted",
              "type": "boolean",
              "required": false,
              "description": "—"
            }
          ],
          "example": "{\"type\":\"thinking\",\"thinking\":\"Consider the file layout...\",\"thinkingSignature\":\"sig\"}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L428-L436"
        },
        {
          "type": "toolCall",
          "concept": "tool-call",
          "summary": "Model's request to run a tool (assistant only).",
          "when": "Inside assistant content; result follows as a toolResult message entry.",
          "fields": [
            {
              "name": "type",
              "type": "\"toolCall\"",
              "required": true,
              "description": "—"
            },
            {
              "name": "id",
              "type": "string",
              "required": true,
              "description": "Matched by toolResult.toolCallId."
            },
            {
              "name": "name",
              "type": "string",
              "required": true,
              "description": "—"
            },
            {
              "name": "arguments",
              "type": "object",
              "required": true,
              "description": "{} when argumentsError is set."
            },
            {
              "name": "thoughtSignature",
              "type": "string",
              "required": false,
              "description": "Google opaque signature."
            },
            {
              "name": "namespace",
              "type": "string",
              "required": false,
              "description": "OpenAI Responses tool namespace."
            },
            {
              "name": "argumentsError",
              "type": "string",
              "required": false,
              "description": "Raw text and error when model sent invalid JSON arguments.",
              "since": "1.3.0"
            }
          ],
          "example": "{\"type\":\"toolCall\",\"id\":\"call_1\",\"name\":\"bash\",\"arguments\":{\"command\":\"ls\"}}",
          "reference": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/ai/src/types.ts#L444-L457"
        }
      ],
      "linking": [
        {
          "topic": "ordering",
          "rule": "File order is append order. Line 1 is the header. Conversation order on a branch comes from walking parentId, not from line order, because branches interleave in one file."
        },
        {
          "topic": "message parent links",
          "rule": "Every non-header entry (all types, including model_change, label, usage) is a tree node whose parentId is the leaf at append time. Build an id index, then walk parentId from a leaf to null."
        },
        {
          "topic": "branches/rewind",
          "rule": "The active leaf is not stored: on load it is the last entry in the file. Branching moves the leaf in memory and the next append gets an earlier parentId; branch_summary records a summarised switch (parentId = branch point, fromId = old leaf). resetLeaf()/branchWithSummary(null) can create extra roots (parentId null). Leaves = entries with no children."
        },
        {
          "topic": "tool call ↔ result",
          "rule": "assistant content block {type:toolCall,id} pairs with a later message entry with role toolResult and the same toolCallId; results for one assistant message are appended in call order after the whole batch completes."
        },
        {
          "topic": "turns",
          "rule": "No explicit turn records. A turn starts with a user (or custom_message) entry and runs through assistant/toolResult entries until an assistant message whose stopReason is not toolUse."
        },
        {
          "topic": "compaction",
          "rule": "Use the latest compaction on the active path: model context = compaction.systemMessage (if any) + compactionSummary, then non-system entries from firstKeptEntryId up to the compaction, then everything after it. Raw entries are kept on disk."
        },
        {
          "topic": "context edits",
          "rule": "For each target, the latest context_edit on the selected path wins; replacement null removes it from model context; display/history/usage still use the original."
        },
        {
          "topic": "forks",
          "rule": "/fork and /clone (createBranchedSession) write a new file containing only the root→leaf path (labels dropped and re-emitted at the end, parentIds rechained) with header.parentSession = source path. forkFrom() copies all source entries verbatim into a new file in another cwd. Entry ids are preserved in both."
        },
        {
          "topic": "session settings",
          "rule": "Current model = last model_change or assistant (provider, model) on the path; thinking level = last thinking_level_change (default off)."
        },
        {
          "topic": "resume",
          "rule": "Resume reopens the same file and appends; continueRecent picks the newest file in the cwd directory."
        },
        {
          "topic": "subagents",
          "rule": "No core subagent lineage; subagents are an example extension running separate pi sessions."
        },
        {
          "topic": "sidecar references",
          "rule": "toolResult.details.fullOutputPath and bashExecution.fullOutputPath point to temp files outside the session directory."
        }
      ],
      "versioning": "Header.version: absent=1 (linear, no id/parentId; compaction used firstKeptEntryIndex), 2 (id/parentId tree, since 0.31.0), 3 (message role hookMessage renamed to custom, since 0.35.0). CURRENT_SESSION_VERSION=3 at v1.4.0. Older files are migrated in memory on load and the file is rewritten in place. Additive fields since v3 are not versioned: system messages and compaction.systemMessage (0.86.0), usage entries (0.86.0), context_edit (0.87.0), retain-none compaction (0.87.0), Usage.reasoning (0.80.3), endTurn (0.84.2), durationMs (1.1.0), argumentsError (1.3.0). File is created at first user message since 0.99.0.",
      "usage": [
        {
          "field": "message(assistant).usage.input/output/cacheRead/cacheWrite",
          "meaning": "Per-response tokens. reasoning (optional) is a subset of output; cacheWrite1h a subset of cacheWrite."
        },
        {
          "field": "usage.totalTokens",
          "meaning": "Provider total for the call."
        },
        {
          "field": "usage.cost.{input,output,cacheRead,cacheWrite,total}",
          "meaning": "USD computed by pi from its model catalogue."
        },
        {
          "field": "toolResult.usage",
          "meaning": "Nested model work by the tool; counted in session totals."
        },
        {
          "field": "usage entry, compaction.usage, branch_summary.usage",
          "meaning": "Non-conversation model calls; included in session totals. Sum across all branches in the file for total spend; across the active path only for that branch."
        }
      ],
      "gotchas": [
        "Branches share one file: reading lines in order mixes alternate branches. Walk parentId from the chosen leaf.",
        "The active leaf is not persisted; pi assumes the last line is the leaf, which after a non-summarised branch switch may be on a different branch than an earlier tail.",
        "Two timestamps: entry.timestamp is ISO 8601; message.timestamp is Unix ms (request start for assistant).",
        "Non-message entries (model_change, label, usage, custom, context_edit) are tree nodes too and sit between messages on the parent chain.",
        "role custom normally appears as a custom_message entry, not inside a message entry; compactionSummary and branchSummary roles are never persisted as messages.",
        "Errored and aborted assistant messages are persisted; error recovery may later hide them via context_edit rather than deleting them.",
        "user content may be a plain string or a block array.",
        "Opening an old-version file rewrites it on disk with the current version.",
        "label clear is written as a label entry without a label key (undefined dropped by JSON.stringify).",
        "branch_summary.fromId can be the literal string \"root\"."
      ],
      "evidence": [
        "transcript-format-pi-packages-agent-src-agent-loop-ts",
        "transcript-format-pi-packages-ai-src-types-ts",
        "transcript-format-pi-packages-coding-agent-docs-message-types-md",
        "transcript-format-pi-packages-coding-agent-docs-session-format-md",
        "transcript-format-pi-packages-coding-agent-examples-extensions-subagent",
        "transcript-format-pi-packages-coding-agent-src-config-ts",
        "transcript-format-pi-packages-coding-agent-src-core-agent-session-ts",
        "transcript-format-pi-packages-coding-agent-src-core-cache-warmer-ts",
        "transcript-format-pi-packages-coding-agent-src-core-messages-ts",
        "transcript-format-pi-packages-coding-agent-src-core-sdk-ts",
        "transcript-format-pi-packages-coding-agent-src-core-session-manager-ts",
        "transcript-format-pi-packages-coding-agent-src-core-tools-bash-ts",
        "transcript-format-pi-packages-coding-agent-src-core-virtual-models-ts",
        "transcript-format-pi-packages-coding-agent-src-modes-interactive-bug-report-ts",
        "transcript-format-pi-packages-coding-agent-src-utils-output-files-ts"
      ],
      "references": {
        "location": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/config.ts#L605-L660",
        "records": "https://github.com/earendil-works/pi/blob/4a080252f06caf63a525d7873c5d94d3c23887e0/packages/coding-agent/src/core/session-manager.ts#L43-L50"
      }
    }
  ]
}