Check Codex Tool Calls with the Hooks Server
Codex runs a PreToolUse hook before each tool call.
Codex has no HTTP hook type, so the hook is a command that sends the call to the Guardrails hooks server (nemoguardrails hooks-server) at /v1/hooks/codex with curl, and prints the answer for Codex to read.
When the hooks server denies a call, Codex blocks it and shows the reason to its model.
Prerequisites
Before you configure the hook, meet the following prerequisites:
-
Codex 0.124.0 or later, the first release with hooks enabled by default, configured in
config.toml, and run forapply_patchand MCP tools. -
A running hooks server. To start one with the Codex example configuration, run the following command from a clone of the repository:
To write your own configuration, refer to Run the Hooks Server: Write a Hooks Configuration. If you list tools in
allowed_tools, setallow_unlisted_tools: falseto deny every tool you leave out: the hooks server refuses to start an allowlist that leaves it unset. -
curlon the machine that runs Codex.
Add the Hook
Add a PreToolUse command hook to your Codex config.toml, such as ~/.codex/config.toml:
The command sends the hook input from standard input to the hooks server, and prints the response for Codex to read.
The hook has no matcher, so Codex runs it for every tool.
If the hooks server runs on another port, for example because you run one server for each agent, change the port in the URL.
Codex blocks a call only when the hook exits 2 with a reason on standard error, or prints a deny.
For any other failure, including a hook that runs past its timeout, Codex marks the hook as failed and runs the tool.
So the command turns every failure into exit code 2:
-fmakescurlexit with an error on any HTTP error status, such as500when a rail fails. Without-f,curlexits0and prints the error body as the hook’s output, which Codex rejects, and the tool runs.--max-time 25makescurlgive up before Codex’stimeoutof 30 seconds, so a slow or hung hooks server ends in acurlerror rather than a timed-out hook.|| exit 2turns everycurlfailure, including a refused connection or--max-timerunning out, into exit code2.-sSkeeps progress output off standard error, but still printscurl’s error message, which becomes the reason Codex reports.
Set timeout, in seconds, to how long your slowest rail can take, and --max-time a few seconds below it.
A rail that calls a model, such as a tool safety check, takes longer than a regular expression.
Leave the hook synchronous: an async hook cannot block a call.
Trust the Hook
From Codex 0.129.0, Codex runs a new or changed hook only after you review and trust it, except a managed hook. Until you do, Codex skips the hook, and every tool call runs unchecked. Follow Review and trust hooks in the Codex documentation.
For automated tests only, Codex 0.131.0 and later accept --dangerously-bypass-hook-trust, which runs hooks without the review.
Do not use it for real sessions.
Deploy the Hook with Managed Settings
Anyone who can edit a user’s config.toml can remove the hook, point it at another server, or drop || exit 2.
To enforce the hook for every user, install it as a managed hook in requirements.toml:
- Codex trusts hooks in
requirements.tomlby policy, and users cannot disable them. - Pin
[features].hooks = trueinrequirements.tomltoo, so the hook runs even for users who turned hooks off. allow_managed_hooks_only = true, from Codex 0.131.0, makes Codex ignore hooks from user, project, and session configuration.
For the file locations and format, refer to Managed hooks from requirements.toml in the Codex documentation.
Verify the Hook
Send a tool call through the same command, the way Codex does, and check the output and the exit code.
-
Send a destructive command, which the example configuration blocks:
The command prints the deny response and exits
0, and Codex reads the deny from the output: -
Stop the hooks server and send the call again. The command prints
curl’s error and exits2, so Codex blocks the call: -
Start the hooks server again, then ask Codex to run a command that your configuration blocks. Codex reports the call as blocked, with the reason.
Codex Tool Names
The hooks server matches tool names exactly as Codex sends them:
Codex reports file edits as apply_patch even when a hook’s matcher names Edit or Write.
To check the files a patch touches, match the file headers in the patch text, as the example configuration does.
From Codex 0.135.0, hooks cover most local function tools, so with allow_unlisted_tools: false, list each one you use in allowed_tools.
Some specialized tool paths can bypass hooks.
Sending input to an existing command with write_stdin does not run PreToolUse again.
Hosted tools that run on the model provider’s side, such as web search, never reach the hook. For the full list, refer to Tool coverage in the Codex documentation. Codex’s own documentation recommends treating tool hooks as a useful guardrail rather than a complete enforcement boundary.
Request and Response
The hooks server reads four fields from the Codex PreToolUse input: hook_event_name, tool_name, tool_input, and tool_use_id.
Codex also sends fields such as session_id, cwd, model, and turn_id, which the hooks server accepts and ignores.
A request without one of the four fields gets HTTP 422.
The following example is a file edit, with placeholder values in angle brackets:
An allowed call gets an empty object, which carries no decision, so Codex runs the tool under its own approval settings:
A denied call gets a deny decision, with the reason prefixed with NeMo Guardrails: :
For every outcome and error, refer to Hooks Server Results and Errors. For the endpoint’s full reference, refer to Hooks Server API: Check a Codex Tool Call.
Related Topics
- Run the Hooks Server
- Check Claude Code Tool Calls with the Hooks Server
- Hooks in the Codex documentation