Module protocol 

App-server v2 protocol types for the Codex CLI.

These types represent the JSON-RPC request parameters, response payloads, and notification bodies used by codex app-server. All wire types use camelCase field names via #[serde(rename_all = "camelCase")].

Organization

• Request/Response pairs — ThreadStartParams/ThreadStartResponse, TurnStartParams/TurnStartResponse, etc.
• Server notifications — Structs like TurnCompletedNotification, AgentMessageDeltaNotification that can be deserialized from the params field of a ServerMessage::Notification
• Approval flow types — CommandExecutionApprovalParams and FileChangeApprovalParams for server-to-client requests that need a response
• Method constants — The methods module contains all JSON-RPC method name strings

Parsing notifications

use codex_codes::protocol::{methods, TurnCompletedNotification};
use serde_json::Value;

fn handle_notification(method: &str, params: Option<Value>) {
    if method == methods::TURN_COMPLETED {
        if let Some(p) = params {
            let notif: TurnCompletedNotification = serde_json::from_value(p).unwrap();
            println!("Turn {} completed", notif.turn_id);
        }
    }
}

Modules

methods

JSON-RPC method names used by the app-server protocol.

Structs

AgentMessageDeltaNotification

item/agentMessage/delta notification.

ClientInfo

Client info sent during the initialize handshake.

CmdOutputDeltaNotification

item/commandExecution/outputDelta notification.

CommandExecutionApprovalParams

Parameters for item/commandExecution/requestApproval (server → client).

CommandExecutionApprovalResponse

Response for item/commandExecution/requestApproval.

ErrorNotification

error notification.

FileChangeApprovalParams

Parameters for item/fileChange/requestApproval (server → client).

FileChangeApprovalResponse

Response for item/fileChange/requestApproval.

FileChangeOutputDeltaNotification

item/fileChange/outputDelta notification.

InitializeCapabilities

Client capabilities negotiated during initialize.

InitializeParams

Parameters for the initialize request.

InitializeResponse

Response from the initialize request.

ItemCompletedNotification

item/completed notification.

ItemStartedNotification

item/started notification.

ReasoningDeltaNotification

item/reasoning/summaryTextDelta notification.

ThreadArchiveParams

Parameters for thread/archive.

ThreadArchiveResponse

Response from thread/archive.

ThreadInfo

Thread metadata returned inside a ThreadStartResponse.

ThreadStartParams

Parameters for thread/start.

ThreadStartResponse

Response from thread/start.

ThreadStartedNotification

thread/started notification.

ThreadStatusChangedNotification

thread/status/changed notification.

ThreadTokenUsageUpdatedNotification

thread/tokenUsage/updated notification.

TokenUsage

Cumulative token usage for a thread.

Turn

A completed turn with its items and final status.

TurnCompletedNotification

turn/completed notification.

TurnError

Error information from a failed turn.

TurnInterruptParams

Parameters for turn/interrupt.

TurnInterruptResponse

Response from turn/interrupt.

TurnStartParams

Parameters for turn/start.

TurnStartResponse

Response from turn/start.

TurnStartedNotification

turn/started notification.

Enums

CommandApprovalDecision

Decision for command execution approval.

FileChangeApprovalDecision

Decision for file change approval.

ServerMessage

An incoming message from the app-server that the client should handle.

ThreadStatus

Status of a thread, sent via ThreadStatusChangedNotification.

TurnStatus

Status of a turn within a Turn.

UserInput

User input sent as part of a TurnStartParams.