Items

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:

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

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

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.

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.

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.

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.

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:

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

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.

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.

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.

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.

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.

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.

string

required

Item identifier

review

string

required

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

exitedReviewMode

Emitted when the reviewer finishes.

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.

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:

item/started

Shows pending commandExecution item

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

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

serverRequest/resolved

Confirms the request was resolved

item/completed

Final item with execution result

File Change Approval

Order of messages:

item/started

Emits fileChange item with diff summaries

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

Client response

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

Possible decisions:

accept - Approve the changes
decline - Deny the changes

serverRequest/resolved

Confirms the request was resolved

item/completed

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

Next Steps

Models

List available models and capabilities

Skills

Manage and invoke skills

App Server API

TypeScript SDK

Item Lifecycle

Item Types

userMessage

agentMessage

plan

reasoning

commandExecution

fileChange

mcpToolCall

dynamicToolCall

webSearch

imageView

enteredReviewMode

exitedReviewMode

contextCompaction

Item Notifications Summary

Approvals

Command Execution Approval

File Change Approval

Next Steps

Models

Skills

App Server API

TypeScript SDK

​Item Lifecycle

​Item Types

​userMessage

​agentMessage

​plan

​reasoning

​commandExecution

​fileChange

​mcpToolCall

​dynamicToolCall

​webSearch

​imageView

​enteredReviewMode

​exitedReviewMode

​contextCompaction

​Item Notifications Summary

​Approvals

​Command Execution Approval

​File Change Approval

​Next Steps

Models

Skills

Item Lifecycle

Item Types

userMessage

agentMessage

plan

reasoning

commandExecution

fileChange

mcpToolCall

dynamicToolCall

webSearch

imageView

enteredReviewMode

exitedReviewMode

contextCompaction

Item Notifications Summary

Approvals

Command Execution Approval

File Change Approval

Next Steps