← All docs

Codex

Wire agentjail into Codex's pre-tool-use hook to enforce policy before every tool call.

agentjail supports Codex CLI. agentjail install auto-detects Codex when ~/.codex/ exists or codex is on your PATH, and wires the hook automatically.

Want the OS sandbox and network visibility too? The hook guards tool calls. To also run Codex inside the kernel sandbox (Seatbelt/Landlock) and capture its LLM traffic, launch it with agentjail run -- codex. See the OS-native sandbox.

Install

Quick install (recommended):

curl -fsSL https://agentjail.io/install.sh | sh

The script runs agentjail install, which presents an interactive picker of all detected agents including Codex. Press Enter to wire them all.

Wire Codex specifically:

agentjail install --for codex

Homebrew:

brew install LuD1161/tap/agentjail
agentjail install --for codex

Both paths work on macOS and Linux.

What the installer writes

agentjail install --for codex adds a PreToolUse hook entry to ~/.codex/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.agentjail/bin/agentjail-hook --agent=codex",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Every tool call Codex makes will pass through agentjail-hook before execution.

Native approval for Bash asks

With agentjail v1.3.0 and Codex 0.146, an effective ask decision for a Bash tool call opens Codex’s native shell approval prompt. This applies whether the ask came from core policy, a library pack, AWS policy, resolver policy, project policy, or a custom rule.

The hook does not place the original command in an approval token. It replaces the call with a fixed broker command carrying an opaque, single-use challenge and a bounded explanation of why approval is required. AgentJail shows a bounded, redacted copy of the original command beside the native prompt. If you approve, the broker validates the challenge and executes the original command once.

For a normal policy ask, the explanation comes from the selected policy outcome. Host CLI access is different: the agent must supply its intent through agentjail proxy --reason "..." -- <command>. Codex shows that reason in the native prompt, and AgentJail binds it to prompt observation and redemption so it cannot be changed after review.

Redemption is bound to the typed operation, exact reason, active Codex session, tool-call epoch, working directory, same-UID peer, and fresh process ancestry. Decline, replay, expiry, daemon restart, version skew, or an identity check that cannot be verified fails closed without running the original command.

This transport is Bash-only. If policy returns ask for a non-Bash tool call, the adapter sends Codex a denial because PreToolUse cannot open an equivalent native prompt for that operation. The decision record still keeps the canonical policy_action=ask separate from the effective denial.

Verify it is working

You can test agentjail-hook directly from the terminal (the daemon must be running). Pipe a synthetic PreToolUse event to the hook and inspect the output:

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | agentjail-hook

The hook prints a JSON response:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "..."
  }
}

Exit 0 means allow or a successful Bash-ask handoff; exit 2 means deny.

For a full explanation of the hook protocol, see the generic hook guide.