How do I track every tool call in Codex (beta)?

Rius records each tool call in a Codex (beta) session as its own span inside that session’s trace, once you install the Rius plugin, trust its hooks and turn tracing on for a folder. A folder enabled with $rius:rius-enable-here sends tool names, timing and error types. $rius:rius-enable-content-here also sends tool inputs and outputs. You then find the calls in the trace list, under the codex agent, and by asking Codex over MCP.

How it works

The Rius plugin hooks into Codex (beta) and sends one trace per session. Tool calls are recorded by the plugin’s PostToolUse hook, one of five hooks you approve in Codex.

The trace has this shape:

• The session is the root span.
• Each turn, one prompt and everything it caused, is a span under it.
• Each model call is a span with its model and token counts.
• Each tool call is a TOOL span under the model call that requested it.
• A spawn_agent tool call marks where a subagent started. The subagent appears under it with its own turns and calls.

A command that exits non-zero is marked as an error on its span, and so is a failed MCP tool.

What each tool span carries depends on how you enable the folder:

• Structure only (default): tool names, error types, timing and status.
• With content: also tool inputs and outputs. The plugin replaces secrets it recognizes with a marker and caps each value at 32 KB. Redaction is best effort, so a secret in a format it does not know is sent.

Tracing is off for every folder until you enable one, and installing the plugin sends nothing.

Set it up

1. Check the requirements. Codex (beta) tracing needs plugin 0.6.0 or later, which is tested with codex-cli 0.144.1, and Python 3.9 or later on your PATH. It runs on macOS or Linux. Windows is untested.

2. Install the plugin. In a terminal:

codex plugin marketplace add glassflow/rius-coding-agents
codex plugin add rius@rius-coding-agents

3. Trust the hooks. In Codex (beta), open /hooks and trust the five rius hooks: SessionStart, UserPromptSubmit, PostToolUse, Stop and SubagentStop. Until you do, nothing is traced and Codex does not tell you. PostToolUse is the hook that records tool calls.

4. Sign in. Type $rius:rius-login, approve the sandbox escalation, choose a workspace in the browser and click Connect.

5. Turn tracing on for the folder. Run one of these in your repo:

$rius:rius-enable-here
$rius:rius-enable-content-here

The first sends tool names, error types and timing. The second adds tool inputs and outputs. A folder you disable with $rius:rius-disable-here always wins over an enabled parent.

6. Confirm. Run $rius:rius-status. Its Hooks: line counts the approved hooks, and the Reason line tells you why a folder is or is not traced.

The Codex (beta) guide covers sign-in, key handling and uninstalling in full.

7. Query the calls from Codex. Run codex mcp login rius once. This is a second sign-in, separate from $rius:rius-login. Then ask in plain language, for example “Show me my last failed session and which command went wrong.”

What you get

• One span per tool call, nested under the model call that requested it, so you see the order of calls inside each turn.
• Error marking on a command that exits non-zero or an MCP tool that fails.
• Subagent visibility. Each spawn_agent call shows where a subagent began, with the subagent’s own turns and tool calls nested beneath it.
• Tool inputs and outputs in folders you enable with content, with recognized secrets removed.
• A place to find them. Each session is one trace in the trace list. Sessions appear as an agent named codex on the Agents page, with an open session shown as a live instance. From plugin 0.6.2, spans carry your sign-in email as user.id, so sessions appear under your name on the Users page.

What Codex (beta) does not report:

• A failed tool call is marked as an error only when a command exits non-zero or an MCP tool fails. Other failures look like success.
• Model-call start times are approximate.
• OpenAI does not report cache-write tokens, so none are shown.
• codex exec --ephemeral sessions are not traced, because Codex keeps no record of them for the plugin to read.
• Codex does not tell plugins when a session ends. A trace closes when you start your next Codex session on the same key, once the old process has exited and has been idle for about an hour. Until then it shows as in progress, and the agent’s trace, error and cost figures count a session only after its trace closes.

If tool calls are missing, start with $rius:rius-status: fewer than five approved hooks means you need to trust them in /hooks.

When something else fits

• If you also use other coding agents, the same plugin covers them. See Coding agents to compare what each reports.
• For a team rollout with per-developer cost, Track Claude Code usage and cost across a team shows the same pattern for Claude Code, with a short Codex (beta) section.

Related