Codex

The Codex adapter translates OpenAI Codex's hook events (the CLI and the IDE extension, local runs) to the firewall's normalized actions and its answers back. The policy is the same engine Claude Code uses.

Tested with Codex 0.162.1. Every event shape was captured live: Codex was installed into a temporary npm prefix and run with a throwaway HOME and CODEX_HOME against a local mock model and a local MCP server, with a capture hook saving each event. No real account or key was used.

InstallCopy Anchor Link

launchsafe-firewall install --agent codex                   # $CODEX_HOME/hooks.json (default ~/.codex/hooks.json)
launchsafe-firewall install --agent codex --scope project   # <project>/.codex/hooks.json
launchsafe-firewall doctor

install puts one hook group per event first in each list (matcher * on tool events), keeps your own hooks, saves the original file under ~/.launchsafe-firewall/backups/, records the install and is idempotent. uninstall --agent codex removes exactly the firewall's entries; --restore-backup puts the file back as it was, after saving the current file as hooks.json.before-restore.TIMESTAMP.

Only the tool events get a matcher. Codex 0.162.1 skips a UserPromptSubmit group that has any matcher, silently (captured). Installs from before the fix wrote "*", so on Codex the firewall never saw a prompt: no task scope and no destinations you named. doctor fails on such a file ("Codex prompt hook"); run install --agent codex again.

Hook trustCopy Anchor Link

Codex runs a hook from hooks.json only once you have trusted it, and skips an untrusted hook silently (no warning; the tool runs). A trusted hook whose command, timeout or matcher changes is skipped the same way. Trust is recorded in $CODEX_HOME/config.toml under hooks.state.

The firewall reproduces Codex's hash exactly, so install, which you run yourself in a terminal, records their trust. uninstall and approver init|rotate update it too, and doctor fails when a recorded hash no longer matches a hook as written. The agent itself may neither grant nor revoke trust: a change to hooks.state is denied (FW-TAMPER). You can also review the hooks in Codex with /hooks.

Managed deploymentCopy Anchor Link

launchsafe-firewall install --managed --agent codex --lock-other-hooks --print | sudo tee /etc/codex/requirements.toml

requirements.toml carries the hooks and allow_managed_hooks_only = true, so no user or project hook runs alongside them and none can be removed by the user. Codex's documentation says managed hooks are trusted by policy; this could not be tested without root. doctor reports whether /etc/codex/requirements.toml registers the firewall.

What the adapter mapsCopy Anchor Link

Codex matches an apply_patch chunk's context again after trimming whitespace and folding punctuation. That was not captured, so the firewall judges the result at every place the chunk could match (the most severe wins), and as the worst case when it matches nowhere.

Output protocol (observed)Copy Anchor Link

• PreToolUse blocks with an explicit permissionDecision: "deny" and a reason (the model reads "Command blocked by PreToolUse hook: ..."), or exit 2 with text on stderr.
• permissionDecision: "ask" is unsupported: Codex logs a failure and runs the tool. The firewall never sends it. An action that needs a person is held in the queue and the agent gets the launchsafe-firewall queue approve <id> command.
• Exit 2 with empty stderr, exit 1, a crash, non-JSON output and a timeout all let the tool run. The wrapper prints a line before exit 2, so a failure of the firewall or of Node blocks. A hook that times out (30 s) still fails open.
• PostToolUse context reaches the model as a separate message. Codex cannot replace a built-in tool's output, so secrets in output are not redacted.

Unattended runsCopy Anchor Link

codex exec forces the approval policy to never, and every event then says permission_mode: "bypassPermissions". The adapter treats that, codex exec or -a never in the process ancestry, and approval_policy = "never" in config.toml as unattended: held actions wait in the queue, and the message says nobody was there.

Until a prompt arrives (an install with the old matcher, or a hook that failed), the session has no task scope, so today's rules apply, and no named destinations, so a fetch after outside content is held rather than allowed.

What its hooks cannot doCopy Anchor Link

• Codex's hosted web search and tool_search never reach a hook.
• The hook gets the shell command only, not the model's workdir: relative paths are judged against the session's directory.
• There is no ConfigChange event: a change to hooks.json or config.toml is judged when the agent makes it through a tool, not when something else edits the file.
• A trusted project's .codex/config.toml with [features] hooks = false switches off every hook, yours included (captured). doctor fails on it, and the agent writing it is denied (FW-TAMPER).
• Codex cloud tasks do not run local command hooks.
• A hook timeout lets the tool run.