Transcript format

session_meta

Identifies the thread and records how, where and by which build it was created.

Written 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.

{"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"}}}

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.

turn_context

Model, cwd, approval and sandbox settings that applied to one turn.

Written once per real user turn after model-visible context updates are computed, and again after mid-turn compaction re-establishes context.

{"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"}}

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).

token_usage_record

Best-effort token usage for one completed Responses API response, with running turn and thread totals.

Written after each completed model response.

{"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}}}

compacted

A context compaction checkpoint; when replacement_history is present it is the complete new model history.

Written when the conversation is compacted (manual /compact or automatic).

{"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}}

Legacy ghost_snapshot entries inside replacement_history are stripped on read.

world_state

Persisted comparison state for model-visible world-state diffing (full snapshot or patch).

Written when world-state context is computed for a turn; full snapshots establish a new baseline.

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"world_state","payload":{"full":true,"state":{"example_key":"example_value"}}}

inter_agent_communication

A message between agents in a multi-agent tree, recorded as history of the recipient.

Written when an agent sends a message or task to another agent through the thread submission lifecycle.

{"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}}

Concept is user-message for the recipient: it is input from another agent, not from the human.

inter_agent_communication_metadata

Records whether a delivered inter-agent message triggered a turn.

Written alongside inter-agent message delivery.

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"inter_agent_communication_metadata","payload":{"trigger_turn":false}}

security_risk_score

Security-risk classifier scores for a reviewed tool action; never model- or user-visible.

Written when a security risk classifier scores an action.

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"security_risk_score","payload":{"scores":{"example_classifier":0.02},"call_id":"call_abc"}}

retained_context / verified_answer

Host-only record of user answers verified for a request_user_input-style call, retained for delegated review.

Written when a question/answer exchange is accepted.

{"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}}

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

realtime_item / realtime_session_started

A realtime voice session began.

Written during realtime (voice) sessions; paginated threads only.

Stored only history_mode = paginated only; dropped in legacy

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"realtime_item","payload":{"id":"rt1","realtime_session_id":"rs1","type":"realtime_session_started"}}

RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id.

realtime_item / transcript_segment

A transcribed realtime speech segment (role user or assistant).

Written during realtime (voice) sessions; paginated threads only.

Stored only history_mode = paginated only; dropped in legacy

{"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"}}

RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id.

realtime_item / bem_item_promoted

An existing agent item was presented inside the realtime conversation.

Written during realtime (voice) sessions; paginated threads only.

Stored only history_mode = paginated only; dropped in legacy

{"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"}}}

RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id.

realtime_item / realtime_session_closed

A realtime session ended.

Written during realtime (voice) sessions; paginated threads only.

Stored only history_mode = paginated only; dropped in legacy

{"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"}}

RealtimeItem flattens its content, so payload.type is the content discriminator alongside id and realtime_session_id.

response_item / message (role=user)

A user message as sent to the model (also used for injected user-role context such as AGENTS.md and environment context).

Written when user input is recorded for a turn; also for harness-injected user-role context fragments.

Stored always (both history modes)

{"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}}

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.

response_item / message (role=assistant)

Assistant output text.

Written when the model emits an output message.

Stored always (both history modes)

{"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}}}

Also used for code-mode delivered assistant messages (see retained_context note).

response_item / message (role=developer)

Developer-role instructions/context injected by the harness (permissions, collaboration mode, skills, hook output, etc.).

Written at session start and whenever model-visible context changes.

Stored always (both history modes)

{"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}}

metadata.client_authored=true marks developer text supplied by the client rather than the harness.

response_item / reasoning

Model reasoning item: readable summaries plus (usually) encrypted reasoning content.

Written when the model emits reasoning.

Stored always (both history modes)

{"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..."}}

response_item / function_call

A JSON-arguments function tool call (shell, MCP tools, multi-agent tools, etc.).

Written when the model calls a function tool.

Stored always (both history modes)

{"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"}}

response_item / function_call_output

Result of a function tool call.

Written after the tool finishes.

Stored always (both history modes)

{"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"}}

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.

response_item / custom_tool_call

A freeform (grammar/plain-text input) tool call such as apply_patch or code-mode exec.

Written when the model calls a custom tool.

Stored always (both history modes)

{"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"}}

response_item / custom_tool_call_output

Result of a custom tool call.

Written after the custom tool finishes.

Stored always (both history modes)

{"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"}]}}

response_item / local_shell_call

Responses API built-in local shell call (legacy shell tool).

Written when a model using the local_shell tool runs a command.

Stored always (both history modes)

{"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}}}

Its result is recorded as function_call_output with the same call_id.

response_item / tool_search_call

A tool-search request (deferred tool discovery).

Written when the model searches for tools.

Stored always (both history modes)

{"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"}}}

response_item / tool_search_output

Tools returned by a tool search.

Written after tool search completes.

Stored always (both history modes)

{"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":[]}}

response_item / web_search_call

Hosted web search performed by the Responses API (call and result in one item).

Written when the model uses hosted web search.

Stored always (both history modes)

{"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"}}}

Results are not in this item; paginated rollouts may carry them in item_completed WebSearch.results.

response_item / image_generation_call

Hosted image generation call including the base64 result.

Written when the model generates an image via the hosted tool.

Stored always (both history modes)

{"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="}}

response_item / agent_message

Model-visible inter-agent message (author -> recipient).

Written when a multi-agent v2 message is delivered into this agent's history.

Stored always (both history modes)

{"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."}]}}

response_item / additional_tools

Tool declarations added to the model's tool set at this point in history.

Written when tools are added mid-thread (e.g. after tool search or plugin enablement).

Stored always (both history modes)

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"response_item","payload":{"type":"additional_tools","role":"developer","tools":[{"type":"function","name":"example_tool"}]}}

response_item / configuration_update

Durable input control (reasoning effort) interpreted by the backend at this point in history.

Written when reasoning settings change mid-thread.

Stored always (both history modes)

{"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}}

response_item / compaction

Opaque encrypted compaction item returned by remote compaction; replaces summarized history for the model.

Written on remote/model-backed compaction.

Stored always (both history modes)

{"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}}

Read alias: compaction_summary.

response_item / context_compaction

Context-compaction item from the Responses API (optionally encrypted).

Written on server-side context compaction.

Stored always (both history modes)

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"response_item","payload":{"type":"context_compaction","id":"cc_123"}}

event_msg / task_started

A turn began.

Written at the start of every turn (regular, review, compact, user shell).

Stored always (both history modes)

{"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"}}

Serialized name is task_started; turn_started is accepted as an alias on read.

event_msg / task_complete

A turn finished (successfully or with a terminal error).

Written at the end of a turn.

Stored always (both history modes)

{"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}}

Serialized name task_complete; alias turn_complete on read.

error.codex_error_info is an enum; misalignment details are never persisted.

event_msg / turn_aborted

A turn was interrupted, replaced, ended by review, or budget-limited.

Written when a turn is aborted.

Stored always (both history modes)

{"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}}

event_msg / token_count

Cumulative and last-response token usage plus rate-limit snapshot.

Written after each model response and on rate-limit updates.

Stored always (both history modes)

{"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}}}

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.

event_msg / thread_settings_applied

Snapshot of thread-level settings after they were applied.

Written when thread settings are applied or changed.

Stored always (both history modes)

{"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":[]}}}

event_msg / thread_goal_updated

The thread's goal (objective, status, budget) changed.

Written when a goal is created or updated.

Stored always (both history modes)

{"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}}}

event_msg / thread_rolled_back

The last N user turns were removed from model context (rewind).

Written when the user rolls back turns.

Stored always (both history modes)

{"timestamp":"2026-01-02T03:04:05.678Z","ordinal":7,"type":"event_msg","payload":{"type":"thread_rolled_back","num_turns":1}}

Concept is branches/rewind; see linking. Earlier records stay in the file.

event_msg / item_completed

Wrapper for a completed TurnItem (the paginated-mode canonical item stream).

Written when any turn item completes. Legacy mode keeps only items with no other lossless representation.

Stored 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

{"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}}

event_msg / user_message

UI-level user message (legacy history).

Written when the user submits input (legacy mode).

Stored only history_mode = legacy only

{"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":[]}}

Contains the user's text without injected context, unlike response_item/message role=user.

event_msg / agent_message

UI-level assistant message (legacy history).

Written when the assistant produces a message (legacy mode).

Stored only history_mode = legacy only

{"timestamp":"2026-01-02T03:04:05.678Z","type":"event_msg","payload":{"type":"agent_message","message":"Done.","phase":"final_answer","memory_citation":null}}

event_msg / agent_reasoning

UI-level reasoning summary text (legacy).

Written when a reasoning summary is produced (legacy).

Stored only history_mode = legacy only

{"timestamp":"2026-01-02T03:04:05.678Z","type":"event_msg","payload":{"type":"agent_reasoning","text":"**Inspecting** the test."}}

event_msg / agent_reasoning_raw_content

UI-level raw reasoning text (legacy).

Written when raw reasoning is exposed (legacy).

Stored only history_mode = legacy only

{"timestamp":"2026-01-02T03:04:05.678Z","type":"event_msg","payload":{"type":"agent_reasoning_raw_content","text":"..."}}

event_msg / entered_review_mode

A /review sub-turn started (legacy).

Written when review mode starts.

Stored only history_mode = legacy only

{"timestamp":"2026-01-02T03:04:05.678Z","type":"event_msg","payload":{"type":"entered_review_mode","target":{"type":"uncommittedChanges"},"user_facing_hint":"current changes"}}

event_msg / exited_review_mode

A review finished, with structured findings (legacy).

Written when review mode ends.

Stored only history_mode = legacy only

{"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}}}

event_msg / patch_apply_end

Outcome of applying a patch (legacy).

Written after apply_patch completes.

Stored only history_mode = legacy only

{"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"}}

event_msg / context_compacted

Marker that context was compacted (legacy).

Written after compaction.

Stored only history_mode = legacy only

{"timestamp":"2026-01-02T03:04:05.678Z","type":"event_msg","payload":{"type":"context_compacted"}}

event_msg / mcp_tool_call_end

Completed MCP tool call with invocation and result (legacy).

Written after an MCP tool call.

Stored only history_mode = legacy only

{"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"}]}}}}

event_msg / web_search_end

Completed web search with query and action (legacy).

Written after a web search.

Stored only history_mode = legacy only

{"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"}}}

event_msg / image_generation_end

Completed image generation (legacy).

Written after image generation.

Stored only history_mode = legacy only

{"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"}}

event_msg / sub_agent_activity

A sub-agent was started, interacted with, or interrupted (legacy).

Written on sub-agent lifecycle activity (kind=completed is stored as an item_completed SubAgentActivity instead).

Stored only history_mode = legacy and kind != completed

{"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"}}

event_msg / item_completed / UserMessage

User input for the turn as the user entered it (no injected context).

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / AgentMessage

Assistant message as displayed.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / Reasoning

Reasoning summary and raw text as displayed.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / Plan

Plan text produced in plan collaboration mode.

Written when the item completes within a turn.

Stored always (both history modes)

{"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}}

event_msg / item_completed / CommandExecution

A shell command run, with output and exit code.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

Older files also carry stdout, stderr and formatted_output, which current builds ignore.

event_msg / item_completed / FileChange

Patch application result with per-file changes.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / McpToolCall

MCP tool invocation with result (camelCase fields).

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / DynamicToolCall

Client-implemented dynamic tool call with result.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / FunctionCallOutput

Function tool output as a display item.

Written when the item completes within a turn.

Stored always (both history modes)

{"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}}

event_msg / item_completed / CollabAgentToolCall

A multi-agent tool call (spawn, send, wait, close...) with target agents and states.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / SubAgentActivity

Sub-agent lifecycle activity.

Written when the item completes within a turn.

Stored only paginated: all kinds; legacy: kind=completed only

{"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}}

event_msg / item_completed / WebSearch

Hosted web search display item.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / ImageView

The agent viewed a local image.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / ImageGeneration

Hosted image generation display item.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / HookPrompt

Prompt fragments injected by hooks.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / EnteredReviewMode

Review mode started.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / ExitedReviewMode

Review finished with output.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / ContextCompaction

Display marker for a context compaction.

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / Extension / web.search

Standalone web-search extension item (camelCase).

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

event_msg / item_completed / Extension / clock.sleep

The agent slept/waited.

Written when the item completes within a turn.

Stored always (both history modes)

{"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}}

event_msg / item_completed / Extension / image_gen.generation

Standalone image-generation extension item (camelCase).

Written when the item completes within a turn.

Stored only history_mode = paginated

{"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}}

message.content / input_text

Text sent to the model (user, developer, injected context).

Written inside the parent record named in type.

{"type":"input_text","text":"Fix the failing test."}

message.content / input_image

Image sent to the model, inline (data URL) or by file id.

Written inside the parent record named in type.

{"type":"input_image","image_url":"data:image/png;base64,iVBORw0KGgo=","detail":"high"}

message.content / input_audio

Audio sent to the model.

Written inside the parent record named in type.

{"type":"input_audio","audio_url":"data:audio/wav;base64,UklGRg=="}

message.content / output_text

Assistant output text.

Written inside the parent record named in type.

{"type":"output_text","text":"Done."}

reasoning.summary / summary_text

Readable reasoning summary part.

Written inside the parent record named in type.

{"type":"summary_text","text":"Inspecting the test."}

reasoning.content / reasoning_text

Raw reasoning text part.

Written inside the parent record named in type.

{"type":"reasoning_text","text":"..."}

reasoning.content / text

Raw reasoning text part (alternate form).

Written inside the parent record named in type.

{"type":"text","text":"..."}

agent_message.content / input_text

Plain inter-agent message text.

Written inside the parent record named in type.

{"type":"input_text","text":"Run the linter."}

agent_message.content / encrypted_content

Encrypted inter-agent message.

Written inside the parent record named in type.

{"type":"encrypted_content","encrypted_content":"gAAAA..."}

tool output (string form)

function_call_output.output / custom_tool_call_output.output as a bare JSON string.

Written inside the parent record named in type.

"Process exited with code 0"

tool output / input_text

Text part of a structured tool output.

Written inside the parent record named in type.

{"type":"input_text","text":"ok"}

tool output / input_image

Image returned by a tool.

Written inside the parent record named in type.

{"type":"input_image","image_url":"data:image/png;base64,iVBORw0KGgo="}

tool output / input_audio

Audio returned by a tool.

Written inside the parent record named in type.

{"type":"input_audio","audio_url":"data:audio/wav;base64,UklGRg=="}

tool output / encrypted_content

Encrypted tool output part.

Written inside the parent record named in type.

{"type":"encrypted_content","encrypted_content":"gAAAA..."}

UserMessage.content / text

User text with UI element spans.

Written inside the parent record named in type.

{"type":"text","text":"Fix it","text_elements":[]}

UserMessage.content / image

Image by URL/data URL or file id.

Written inside the parent record named in type.

{"type":"image","image_url":"data:image/png;base64,iVBORw0KGgo="}

UserMessage.content / local_image

Image attached from a local path (bytes not stored in this block).

Written inside the parent record named in type.

{"type":"local_image","path":"/home/user/shot.png"}

UserMessage.content / audio

Audio by URL.

Written inside the parent record named in type.

{"type":"audio","audio_url":"data:audio/wav;base64,UklGRg=="}

UserMessage.content / local_audio

Audio from a local path.

Written inside the parent record named in type.

{"type":"local_audio","path":"/home/user/a.wav"}

UserMessage.content / skill

Explicitly selected skill.

Written inside the parent record named in type.

{"type":"skill","name":"example-skill","path":"/home/user/.codex/skills/example/SKILL.md"}

UserMessage.content / mention

@-mention of a resource.

Written inside the parent record named in type.

{"type":"mention","name":"README.md","path":"README.md"}

AgentMessage.content / Text

Display text of an AgentMessage item (PascalCase type).

Written inside the parent record named in type.

{"type":"Text","text":"Done."}

DynamicToolCall.content_items / inputText|inputImage|inputAudio

Dynamic tool output parts (camelCase type and fields).

Written inside the parent record named in type.

{"type":"inputText","text":"ok"}

McpToolCall.result.content / <MCP content block>

Opaque MCP content blocks (text, image, resource, ...), passed through as JSON.

Written inside the parent record named in type.

{"type":"text","text":"result"}

user

A user-role message: a typed prompt, a slash-command expansion, injected meta text, or (most often) one tool_result answering a tool_use.

Written on prompt submit; after every tool execution (one line per tool_result); for meta/caveat injections and compaction summaries.

{"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"}

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).

assistant

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.

Written as each content block of an API response completes (thinking, text, tool_use).

{"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}}}

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.

system / turn_duration

Marks the end of a turn with its wall time and message count.

Written when the main loop finishes a turn.

{"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}

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).

system / stop_hook_summary

Summary of Stop/SubagentStop hooks run at the end of a turn.

Written after Stop hooks execute.

{"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"}

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).

system / away_summary

A recap ('while you were away') summarising recent work, shown when the user returns.

Written after idle periods / background completion.

{"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"}

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).

system / compact_boundary

Compaction marker: everything before it is replaced by the following isCompactSummary user entry for model context.

Written on /compact or auto-compact.