Capture routes for Claude Code and Codex

1. Hook events

The hooks reference lists the events, the payloads and the answers. The source is https://code.claude.com/docs/en/hooks.

Hook types. A hook entry has a type of command, http, mcp_tool, prompt or agent. The agent type is experimental. A command hook reads the payload on stdin. An http hook receives the payload as the body of a POST. A command hook can set async: true to run in the background, and an async hook cannot block.

Common input fields. Every event receives session_id, prompt_id, transcript_path, cwd, scratchpad_dir, permission_mode, effort and hook_event_name. Inside a subagent, or with --agent, the payload also has agent_id and agent_type.

Universal answer fields. Every event accepts continue, stopReason, systemMessage and terminalSequence. The value continue: false stops Claude. A command hook blocks with exit code 2. The additionalContext field goes to the model as a system reminder, with a cap of 10,000 characters.

Model calls in hooks. No hook receives a model request or a model response. The nearest data are last_assistant_message on Stop and SubagentStop, the text deltas on MessageDisplay, and PostToolBatch, which fires immediately before the next model call. Hooks give tool calls, prompts and lifecycle events. They give no token counts.

2. Built-in OpenTelemetry

Claude Code exports metrics and log events, and in beta it exports trace spans. The source is https://code.claude.com/docs/en/monitoring-usage.

Switches and exporters:

Content switches. All content is off by default. When content is off, the value is <REDACTED>.

The raw bodies hold the system prompt, every earlier turn and every tool result. Claude Code always removes extended thinking from the raw bodies. Project and local settings cannot set OTEL_LOG_RAW_API_BODIES.

Metrics. The metrics are claude_code.session.count, claude_code.lines_of_code.count, claude_code.pull_request.count, claude_code.commit.count, claude_code.cost.usage, claude_code.token.usage, claude_code.code_edit_tool.decision and claude_code.active_time.total.

Log events. Each name has the prefix claude_code.:

Events carry session.id, prompt.id, event.sequence, message.uuid, request_id, agent_id and parent_agent_id. The prompt.id value links all events from one user prompt. The event.sequence value is a counter for each process.

Spans (beta). The span tree for one prompt has this form:

claude_code.interaction            one span for each user prompt
├── claude_code.llm_request        model, gen_ai.*, tokens, ttft_ms, stop_reason, request_id, attempt
├── claude_code.hook               needs detailed beta tracing
└── claude_code.tool               tool_name, tool_use_id, duration_ms, result_tokens
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution success, error
    └── subagent spans nest under the Agent tool span

Bash subprocesses inherit TRACEPARENT. In -p mode and in Agent SDK sessions, Claude Code reads an inbound TRACEPARENT and TRACESTATE from the environment. So provevi can set the parent trace.

3. Session transcripts

Claude Code writes one JSONL file for each session. The source is https://code.claude.com/docs/en/claude-directory.

• Main file. ~/.claude/projects/<project>/<session>.jsonl. The <project> part is the working folder with each character that is not a letter or digit changed to -.
• Subagents. ~/.claude/projects/<project>/<session>/subagents/ holds subagent transcripts in the same format.
• Large outputs. ~/.claude/projects/<project>/<session>/tool-results/ holds tool outputs that were too large for the main file.
• Retention. Claude Code deletes these files after cleanupPeriodDays, which is 30 by default. Set the value higher, or copy the files out, to keep the evidence.

The documentation says the transcript holds messages, tool calls and tool results. It also holds the system prompt, tool definitions and the parameters of each model request. The files are plain text and are not encrypted.

The documentation does not define the line schema, and it makes no promise that the schema is stable. Treat the schema as internal. A local file from v2.1.316 shows these record types:

Message records carry uuid, parentUuid, sessionId, timestamp, isSidechain and version. Thinking blocks may appear in the file. The OTel raw bodies always remove them.

4. Agent SDK capture

The SDK runs the same Claude Code engine, so the hooks and OTel settings above also apply. The sources are https://code.claude.com/docs/en/agent-sdk/hooks, https://code.claude.com/docs/en/agent-sdk/permissions and https://code.claude.com/docs/en/agent-sdk/typescript.

Hook callbacks. Pass hooks in the options. The value maps an event name to a list of matchers.

• Signature. A callback receives (input, tool_use_id, context). In TypeScript, context.signal is an AbortSignal. In Python the argument is reserved.
• Answers. A callback returns the same JSON as a shell hook. It can also return {async: true} (async_ in Python) to log without delay, and then it cannot block.
• Order. Hooks run first, before deny rules, ask rules, the permission mode, allow rules and canUseTool. A hook deny applies even in bypassPermissions mode.

Python and TypeScript differ. Python supports PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PreCompact, PermissionRequest and Notification. TypeScript supports every event in the HookEvent union, which has the same list as the CLI. Python has no SessionStart or SessionEnd callbacks. Load them as shell hooks through setting_sources, or use the first message in the stream.

canUseTool. The callback runs only when the permission flow reaches a prompt. Calls that an allow rule or the permission mode already approved never reach it. Use PreToolUse to see every call. The TypeScript signature is (toolName, input, {signal, suggestions, blockedPath, decisionReason, toolUseID, agentID, requestId}), and it returns a PermissionResult.

Message stream. The stream from query() gives the following SDKMessage types:

The parent_tool_use_id field ties a subagent message to the Agent tool call that started the subagent. Each assistant message gives one model response with its usage. The stream does not give the request body that went to the model.

5. Gaps for Claude Code

• Model request bodies. Hooks and the SDK stream do not give them. Use OTEL_LOG_RAW_API_BODIES with file:<dir>, or the api-request records in the transcript.
• Model responses in hooks. Hooks give only last_assistant_message. Use the SDK stream, the assistant_response event, or the transcript.
• Tokens and cost in hooks. Hooks give none. Use api_request events, llm_request spans, the SDK result message, or usage in the transcript.
• Thinking. OTel always removes extended thinking. Only the transcript or the SDK stream can hold it.
• Content in OTel. Prompts, tool input and tool output are redacted unless each switch is on.
• Spans. Spans are beta. Hook spans need a detailed beta mode that the interactive CLI gets only for allowlisted organizations.
• Async and timeouts. A hook that times out loses its output, and an async hook cannot block. A hook may also not fire when the SDK reaches max_turns.
• Retention. The transcript disappears after cleanupPeriodDays.

6. Hooks, notify and OpenTelemetry

Hooks. Codex now has a hooks system that copies the design of the Claude Code hooks. Hooks are on by default. The source is https://learn.chatgpt.com/docs/hooks.

• Configuration. Put hooks in hooks.json or in a [hooks] table of config.toml, in ~/.codex/ or <repo>/.codex/. Plugins can also ship hooks. Turn hooks off with [features] hooks = false.
• Trust. A person must review each hook that is not managed in /hooks before it runs. A changed hook does not run until a person trusts it again. Managed hooks come from requirements.toml, and allow_managed_hooks_only = true ignores all other sources.
• Handlers. Codex runs command and mcp_tool handlers. It parses prompt and agent handlers but skips them. A command hook with async: true runs in the background.
• Common input. Each payload has session_id, transcript_path (may be null), cwd, hook_event_name and model. Most events also have permission_mode.

Tool hooks cover shell (Bash), unified exec, apply_patch (also matched as Edit or Write), MCP tools and other local function tools. They do not cover hosted tools such as WebSearch. The page calls tool hooks “a useful guardrail, not a complete enforcement boundary”. The page gives no version number.

notify. Set notify = ["python3", "/path/to/notify.py"] in the user config. Codex runs the program with one JSON argument. The only event is agent-turn-complete. The fields are type, thread-id, turn-id, cwd, input-messages and last-assistant-message. The source is https://learn.chatgpt.com/docs/config-file/config-advanced.

OpenTelemetry. Set [otel] in ~/.codex/config.toml. A project config cannot set it. The sources are https://learn.chatgpt.com/docs/config-file/config-advanced, https://learn.chatgpt.com/docs/config-file/config-reference and the crate README at https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/otel/README.md.

The otel.log_agent_responses, otel.log_guardian_assessments, otel.span_attributes and otel.tracestate keys come from the crate README. The configuration reference page did not show them.

Codex log events include codex.conversation_starts, codex.api_request, codex.sse_event, codex.websocket_request, codex.websocket_event, codex.user_prompt, codex.tool_decision, codex.tool_result, codex.skill_invocation, codex.sandbox_outcome, codex.turn_ttft and codex.turn_cost. The codex.tool_result event has a duration, a success flag and an output snippet. Token counts arrive on the response.completed SSE event. The metrics include codex.tool.call and codex.tool.call.duration_ms.

Codex emits spans through the Rust tracing crate when trace_exporter is set. The documentation does not name the spans. The source of session_telemetry.rs at v0.166.0 records gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.cache_read.input_tokens and codex.usage.reasoning_output_tokens on the span that handles a model response. Codex logs no raw request bodies or response bodies.

7. Rollout files and codex exec --json

Rollout files. Codex writes each session to ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread-id>.jsonl. Archived sessions move to ~/.codex/archived_sessions/. The constants are in codex-rs/rollout/src/lib.rs. The documentation does not describe the rollout format. The format below comes from the source at v0.166.0 (codex-rs/history/src/rollout_payload.rs, codex-rs/rollout/src/policy.rs) and a local file.

Each line has timestamp, ordinal, type and payload. The type values are these:

Codex cuts command output and MCP results at 64 KB in the rollout file. The reasoning items hold encrypted_content and a summary, so the reasoning text is not readable.

codex exec --json. The command prints one JSON event on each line. The types are in codex-rs/exec/src/exec_events.rs at v0.166.0.

• Thread and turn events. thread.started (thread_id), turn.started, turn.completed (usage with input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens), turn.failed and error.
• Item events. item.started, item.updated and item.completed. Each carries an item with id and type.
• Item types. The table below lists the item types and their fields.

The TypeScript Codex SDK spawns the CLI and reads the same JSONL events. Its runStreamed() call returns them (https://github.com/openai/codex/blob/rust-v0.166.0/sdk/typescript/README.md). The Python SDK uses types that are generated from the app server protocol. Its event stream was not checked in detail.

8. Gaps for Codex

• No raw model requests. No route gives the full request body. The rollout file gives the instructions, the items and the usage, and provevi can rebuild the request from them.
• Encrypted reasoning. Reasoning text is encrypted in the rollout file. Only summaries are readable.
• Hosted tools. Hooks do not cover WebSearch and other hosted tools. The rollout file and exec --json (web_search items) do show them.
• Undocumented spans. The span names are not in the documentation, so they can change in any release.
• Prompt and agent hooks. Codex skips prompt and agent handlers.
• Hook trust. A hook that is not managed does not run until a person trusts it. A headless run needs managed hooks or --dangerously-bypass-hook-trust.
• Truncation. The rollout file cuts tool output at 64 KB. The codex.tool_result event has only a snippet.
• notify. It fires only at the end of a turn.

Claude Code

1. Use a hook as the gate. Register PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStart, SubagentStop, Stop, PreCompact, SessionStart and SessionEnd. Use an http hook to a local provevi daemon, or a command hook. Keep PreToolUse synchronous, so that provevi writes the evidence event before the tool runs. Make the others async.
2. Chain on the hook events. Use session_id, prompt_id, tool_use_id and agent_id as keys. Each hook event becomes one evidence event in the hash chain.
3. Take spans from OTel. Turn on CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_ENHANCED_TELEMETRY_BETA, the OTLP log and trace exporters, and the content switches. Point the exporter at a provevi OTLP receiver. Set TRACEPARENT so that the agent spans join the provevi trace.
4. Keep the model calls as files. Set OTEL_LOG_RAW_API_BODIES=file:<provevi dir>. Hash each request file and response file into the chain. The index.jsonl file links each response to its transcript message.
5. Use the transcript to fill gaps. At Stop, SubagentStop and SessionEnd, read transcript_path and agent_transcript_path. Hash the new lines into the chain. Raise cleanupPeriodDays, because the transcript otherwise goes after 30 days. Do not depend on its line schema. Store the lines as raw bytes.
6. In the Agent SDK, prefer TypeScript. Use the TypeScript SDK, which has every hook event. Record every SDKMessage from the stream with includePartialMessages and includeHookEvents. In Python, add SessionStart and SessionEnd as shell hooks.

Codex

1. Use managed hooks as the gate. Put PreToolUse, PostToolUse, UserPromptSubmit, SubagentStart, SubagentStop, Stop, PreCompact and SessionEnd in requirements.toml, so that they run without a trust prompt. Use command handlers. Keep PreToolUse synchronous.
2. Turn on OTel for spans and model events. Set otel.exporter and otel.trace_exporter to the provevi OTLP receiver. Set log_user_prompt and log_agent_responses to true. Treat span names as unstable and key on attributes such as conversation.id and turn.id.
3. Use the rollout file as the main record of model calls. No other Codex route gives each model response with its usage. Tail the rollout file during the session, or read it at Stop. Hash each line into the chain. Record response_id from token_usage_record as the model call identity.
4. Use codex exec --json or the SDK for automated runs. Record each event. Join it to the rollout file by thread_id.
5. Record what is missing. Store a field in the evidence that says the request body and the reasoning text are not available for Codex. A reader of the evidence then knows that the gap is expected and is not an error.