Items

Thread item types and streaming notifications

ThreadItem is the core data structure representing user inputs and agent outputs within a turn. Items are persisted and used as context for future conversations.

Item Lifecycle

All items follow a consistent lifecycle:

1. item/started

   Emits the full item when a new unit of work begins

   {
     "method": "item/started",
     "params": {
       "threadId": "thr_123",
       "turnId": "turn_456",
       "item": {
         "type": "agentMessage",
         "id": "item_789",
         "text": ""
       }
     }
   }
   
2. Item-specific deltas (optional)

   Zero or more streaming updates

   • item/agentMessage/delta - Agent text streaming
   • item/commandExecution/outputDelta - Command output streaming
   • item/reasoning/summaryTextDelta - Reasoning summary streaming
3. item/completed

   Sends the final item once work finishes

   {
     "method": "item/completed",
     "params": {
       "threadId": "thr_123",
       "turnId": "turn_456",
       "item": {
         "type": "agentMessage",
         "id": "item_789",
         "text": "Here's the complete response..."
       }
     }
   }
   

Item Types

userMessage

User text or image input.

id · string · required

Item identifier

content · UserInput[] · required

Array of user input items (text, image, localImage, skill, mention)

Example:

{
  "type": "userMessage",
  "id": "turn_456",
  "content": [
    { "type": "text", "text": "Run tests" }
  ]
}

agentMessage

Agent response text.

id · string · required

Item identifier

text · string · required

Accumulated agent reply text

phase · MessagePhase

Message phase (when applicable)

Streaming:

{
  "method": "item/agentMessage/delta",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_789",
    "delta": "Here is "
  }
}

Concatenate delta values for the same itemId to reconstruct the full reply.

plan

EXPERIMENTAL - Proposed plan item content.

id · string · required

Item identifier

text · string · required

Plan text

Streaming:

{
  "method": "item/plan/delta",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_plan",
    "delta": "Step 1: Run tests\n"
  }
}

The completed plan item is authoritative and may not match the concatenation of PlanDelta text.

reasoning

Agent reasoning traces.

id · string · required

Item identifier

summary · string[] · required

Streamed reasoning summaries (applicable for most OpenAI models)

content · string[] · required

Raw reasoning blocks (applicable for open source models)

Streaming notifications:

Summary Delta

{
  "method": "item/reasoning/summaryTextDelta",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_reasoning",
    "summaryIndex": 0,
    "delta": "Analyzing the test suite..."
  }
}

commandExecution

Sandboxed shell command.

id · string · required

Item identifier

command · string · required

The command to execute

cwd · string · required

Command working directory

processId · string

PTY process identifier (when available)

status · CommandExecutionStatus · required

inProgress, completed, failed, or declined

commandActions · CommandAction[] · required

Best-effort parsing of command actions

aggregatedOutput · string

Combined stdout/stderr output

exitCode · number

Command exit code

durationMs · number

Execution duration in milliseconds

Streaming:

{
  "method": "item/commandExecution/outputDelta",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_cmd",
    "delta": "Running tests...\n"
  }
}

fileChange

Proposed or applied file edits.

id · string · required

Item identifier

changes · FileUpdateChange[] · required

Array of file changes with path, kind, and diff

status · PatchApplyStatus · required

inProgress, completed, failed, or declined

Streaming:

{
  "method": "item/fileChange/outputDelta",
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456",
    "itemId": "item_file",
    "delta": "Applying patch to src/main.rs...\n"
  }
}

mcpToolCall

MCP (Model Context Protocol) tool invocation.

id · string · required

Item identifier

server · string · required

MCP server name

tool · string · required

Tool name

status · string · required

inProgress, completed, or failed

arguments · object · required

Tool arguments (JSON)

result · object

Tool result (when completed)

error · object

Error details (when failed)

durationMs · number

Call duration in milliseconds

Example:

{
  "type": "mcpToolCall",
  "id": "item_mcp",
  "server": "github",
  "tool": "create_issue",
  "status": "completed",
  "arguments": {
    "title": "Bug report",
    "body": "Description"
  },
  "result": {
    "issue_url": "https://github.com/..."
  },
  "durationMs": 1234
}

dynamicToolCall

Dynamic tool call executed on the client.

id · string · required

Item identifier

tool · string · required

Tool name

arguments · object · required

Tool arguments (JSON)

status · string · required

inProgress, completed, or failed

contentItems · object[]

Output content items (text/images)

success · boolean

Whether the tool call succeeded

durationMs · number

Call duration in milliseconds

webSearch

Web search request issued by the agent.

id · string · required

Item identifier

query · string · required

Search query

action · WebSearchAction

Action payload (search, open_page, find_in_page)

Example:

{
  "type": "webSearch",
  "id": "item_search",
  "query": "rust async trait error handling",
  "action": {
    "type": "search",
    "query": "rust async trait error handling"
  }
}

imageView

Image viewer tool invocation.

id · string · required

Item identifier

path · string · required

Path to the image file

Example:

{
  "type": "imageView",
  "id": "item_img",
  "path": "/tmp/screenshot.png"
}

enteredReviewMode

Emitted when the reviewer starts.

id · string · required

Item identifier

review · string · required

Short user-facing label (e.g., "current changes", "commit abc123")

exitedReviewMode

Emitted when the reviewer finishes.

id · string · required

Item identifier

review · string · required

Full plain-text review (overall notes plus bullet point findings)

Example:

{
  "type": "exitedReviewMode",
  "id": "turn_900",
  "review": "Looks solid overall...\n\n- Prefer Stylize helpers — app.rs:10-20\n  ..."
}

contextCompaction

Emitted when Codex compacts conversation history.

id · string · required

Item identifier

Example:

{
  "type": "contextCompaction",
  "id": "item_compact"
}

Context compaction can happen automatically when the conversation history grows too large.

Item Notifications Summary

item/started · notification

Emits the full item when work begins

item/completed · notification

Sends the final item once work finishes

item/agentMessage/delta · notification

Streams agent message text

item/plan/delta · notification

Streams plan content (experimental)

item/reasoning/summaryTextDelta · notification

Streams reasoning summary text

item/reasoning/summaryPartAdded · notification

Marks reasoning summary section boundaries

item/reasoning/textDelta · notification

Streams raw reasoning text (open source models)

item/commandExecution/outputDelta · notification

Streams command stdout/stderr

item/fileChange/outputDelta · notification

Streams file change tool output

item/mcpToolCall/progress · notification

MCP tool call progress updates

Approvals

Certain actions (shell commands or file changes) may require explicit user approval depending on the approval policy.

Command Execution Approval

Order of messages:

1. item/started

   Shows pending commandExecution item

2. item/commandExecution/requestApproval (server request)

   {
     "method": "item/commandExecution/requestApproval",
     "id": 100,
     "params": {
       "threadId": "thr_123",
       "turnId": "turn_456",
       "itemId": "item_cmd",
       "command": ["rm", "-rf", "/tmp/test"],
       "cwd": "/Users/me/project",
       "commandActions": [...],
       "reason": "Potentially destructive command"
     }
   }
   
3. Client response

   {
     "id": 100,
     "result": {
       "decision": "accept"
     }
   }
   

   Possible decisions:

   • accept - Approve the command
   • acceptForSession - Approve and cache for session
   • acceptWithExecpolicyAmendment - Approve with persistent rule
   • applyNetworkPolicyAmendment - Apply network policy rule
   • decline - Deny the command
   • cancel - Deny and interrupt turn
4. serverRequest/resolved

   Confirms the request was resolved

5. item/completed

   Final item with execution result

File Change Approval

Order of messages:

1. item/started

   Emits fileChange item with diff summaries

2. item/fileChange/requestApproval (server request)

   {
     "method": "item/fileChange/requestApproval",
     "id": 101,
     "params": {
       "threadId": "thr_123",
       "turnId": "turn_456",
       "itemId": "item_file",
       "reason": "File changes require approval"
     }
   }
   
3. Client response

   {
     "id": 101,
     "result": {
       "decision": "accept"
     }
   }
   

   Possible decisions:

   • accept - Approve the changes
   • decline - Deny the changes
4. serverRequest/resolved

   Confirms the request was resolved

5. item/completed

   Final item with status: "completed", "failed", or "declined"

Next Steps

Models

List available models and capabilities

Skills

Manage and invoke skills