Skip to main content

Module protocol

Module protocol

Expand description

Defines the protocol for a Codex session between a client and an agent.

Uses a SQ (Submission Queue) / EQ (Event Queue) pattern to asynchronously communicate between user and agent.

Re-exports§

pub use crate::approvals::ApplyPatchApprovalRequestEvent;
pub use crate::approvals::ElicitationAction;
pub use crate::approvals::ExecApprovalRequestEvent;
pub use crate::approvals::ExecPolicyAmendment;
pub use crate::approvals::GuardianAssessmentAction;
pub use crate::approvals::GuardianAssessmentDecisionSource;
pub use crate::approvals::GuardianAssessmentEvent;
pub use crate::approvals::GuardianAssessmentOutcome;
pub use crate::approvals::GuardianAssessmentStatus;
pub use crate::approvals::GuardianCommandSource;
pub use crate::approvals::GuardianRiskLevel;
pub use crate::approvals::GuardianUserAuthorization;
pub use crate::approvals::NetworkApprovalContext;
pub use crate::approvals::NetworkApprovalProtocol;
pub use crate::approvals::NetworkPolicyAmendment;
pub use crate::approvals::NetworkPolicyRuleAction;
pub use crate::permissions::FileSystemAccessMode;
pub use crate::permissions::FileSystemPath;
pub use crate::permissions::FileSystemSandboxEntry;
pub use crate::permissions::FileSystemSandboxKind;
pub use crate::permissions::FileSystemSandboxPolicy;
pub use crate::permissions::FileSystemSpecialPath;
pub use crate::permissions::NetworkSandboxPolicy;
pub use crate::request_permissions::RequestPermissionsArgs;
pub use crate::request_user_input::RequestUserInputEvent;

Structs§

AdditionalContextEntry: Client-supplied context keyed by an opaque source identifier.
AgentMessageContentDeltaEvent
AgentMessageEvent
AgentReasoningEvent
AgentReasoningRawContentEvent
AgentReasoningSectionBreakEvent
Chunk
CollabAgentInteractionBeginEvent
CollabAgentInteractionEndEvent
CollabAgentRef
CollabAgentSpawnBeginEvent
CollabAgentSpawnEndEvent
CollabAgentStatusEntry
CollabCloseBeginEvent
CollabCloseEndEvent
CollabResumeBeginEvent
CollabResumeEndEvent
CollabWaitingBeginEvent
CollabWaitingEndEvent
CompactedItem
ContextCompactedEvent
ConversationAudioParams
ConversationPathResponseEvent: Response payload for Op::GetHistory containing the current session’s in-memory transcript.
ConversationSpeechParams
ConversationStartParams
ConversationTextParams
CreditsSnapshot
DeprecationNoticeEvent
DynamicToolCallResponseEvent
EnteredReviewModeEvent
EnvironmentConnectionEvent
ErrorEvent
Event: Event Queue Entry - events from agent
ExecCommandBeginEvent
ExecCommandEndEvent
ExecCommandOutputDeltaEvent
ExitedReviewModeEvent
FinalOutput
GitInfo
GitSha
GranularApprovalConfig
HistoryPosition: Exclusive position in another thread’s paginated rollout history.
HookCompletedEvent
HookEventNameIter: An iterator over the variants of HookEventName
HookOutputEntry
HookRunSummary
HookStartedEvent
ImageGenerationBeginEvent
ImageGenerationEndEvent
InterAgentCommunication
ItemCompletedEvent
ItemStartedEvent
McpInvocation
McpServerRefreshConfig: Config payload for refreshing MCP servers.
McpStartupCompleteEvent
McpStartupFailure
McpStartupUpdateEvent
McpToolCallBeginEvent
McpToolCallEndEvent
ModelRerouteEvent
ModelVerificationEvent
PatchApplyBeginEvent
PatchApplyEndEvent
PatchApplyUpdatedEvent
PlanDeltaEvent
RateLimitSnapshot
RateLimitWindow
RawResponseCompletedEvent: Exact usage reported by one upstream Responses API completion.
RawResponseItemEvent
RealtimeAudioFrame
RealtimeConversationClosedEvent
RealtimeConversationListVoicesResponseEvent
RealtimeConversationRealtimeEvent
RealtimeConversationSdpEvent
RealtimeConversationStartedEvent
RealtimeHandoffRequested
RealtimeInputAudioSpeechStarted
RealtimeNoopRequested
RealtimeResponseCancelled
RealtimeResponseCreated
RealtimeResponseDone
RealtimeTranscriptDelta
RealtimeTranscriptDone
RealtimeTranscriptEntry
RealtimeVoicesList
ReasoningContentDeltaEvent
ReasoningRawContentDeltaEvent
ResumedHistory
ReviewCodeLocation: Location of the code related to a review finding.
ReviewFinding: A single review finding describing an observed issue or recommendation.
ReviewLineRange: Inclusive line range in a file associated with the finding.
ReviewOutputEvent: Structured review result produced by a child review session.
ReviewRequest: Review request sent to the review session.
RolloutLine
SafetyBufferingEvent
SessionConfiguredEvent
SessionContextWindow
SessionMeta: SessionMeta contains session-level data that doesn’t correspond to a specific turn.
SessionMetaLine
SessionNetworkProxyRuntime
SkillDependencies
SkillInterface
SkillMetadata
SkillToolDependency
SpendControlLimitSnapshot
StreamErrorEvent
StreamInfoEvent
SubAgentActivityEvent
Submission: Submission Queue Entry - requests from user
TerminalInteractionEvent
ThreadGoal
ThreadGoalUpdatedEvent
ThreadRolledBackEvent
ThreadSettingsAppliedEvent
ThreadSettingsOverrides: Persistent thread-settings overrides that can be applied before user input or on their own.
ThreadSettingsSnapshot
TokenCountEvent
TokenUsage
TokenUsageInfo
TurnAbortedEvent
TurnCompleteEvent
TurnContextItem: Persist once per real user turn after computing that turn’s model-visible context updates, and again after mid-turn compaction when replacement history re-establishes full context, so resume/fork replay can recover the latest durable baseline.
TurnContextNetworkItem
TurnDiffEvent
TurnEnvironmentSelection
TurnEnvironmentSelections
TurnModerationMetadataEvent
TurnStartedEvent
UserMessageEvent
ViewImageToolCallEvent
W3cTraceContext
WarningEvent
WebSearchBeginEvent
WebSearchEndEvent
WorldStateItem: Persisted comparison state used to resume model-visible world-state diffing.
WritableRoot: A writable root path accompanied by a list of subpaths that should remain read‑only even when the root is writable. This is primarily used to ensure that folders containing files that could be modified to escalate the privileges of the agent (e.g. .codex, .git, notably .git/hooks) under a writable root are not modified by the agent.

Enums§

AdditionalContextKind: Source classification for client-supplied context.
AgentStatus: Agent lifecycle status, derived from emitted events.
AskForApproval: Determines the conditions under which the user is consulted to approve running the command proposed by Codex.
CodexErrorInfo: Codex errors that we expose to clients.
CodexResponseHandoffMode
ConversationStartTransport
ConversationTextRole
EventMsg: Response event from the agent NOTE: Make sure none of these values have optional types, as it will mess up the extension code-gen.
ExecCommandSource
ExecCommandStatus
ExecOutputStream
FileChange
HookEventName
HookExecutionMode
HookHandlerType
HookOutputEntryKind
HookRunStatus
HookScope
HookSource
HookTrustStatus
InitialHistory
InternalSessionSource
McpAuthStatus
McpStartupFailureReason
McpStartupStatus
ModelRerouteReason
ModelVerification
MultiAgentVersion
NetworkAccess: Represents whether outbound network access is available to the agent.
NonSteerableTurnKind: Turn kinds that reject same-turn steering.
Op: Submission operation
PatchApplyStatus
Product
RateLimitReachedType
RealtimeConversationVersion
RealtimeEvent
RealtimeOutputModality
RealtimeVoice
ReviewDecision: User’s decision in response to an ExecApprovalRequest.
ReviewDelivery
ReviewTarget
RolloutItem
SandboxPolicy: Determines execution restrictions for model shell commands.
SessionSource
SkillScope
SubAgentActivityKind
SubAgentSource
ThreadGoalStatus
ThreadHistoryMode
ThreadMemoryMode
ThreadSource
TruncationPolicy
TurnAbortReason

Constants§

Traits§

HasLegacyEvent: Converts canonical item lifecycle events back into the legacy raw event stream used by compatibility consumers that have not migrated to TurnItem.

Functions§

strip_user_message_prefix: Removes the model-context prefix from a user message before displaying it.
user_message_preview: Returns the user-facing preview text for a user message.
validate_thread_goal_objective