update Codex hooks reference 3→5 — replace agent-turn-complete with PreToolUse, PostToolUse, UserPromptSubmit

Co-Authored-By: Claude <noreply@anthropic.com>

.codex/hooks/HOOKS-README.md

@@ -3,30 +3,32 @@ Contains all the details, scripts, and instructions for the Codex CLI hooks.
 
 ## Hook Events Overview
 
-Codex CLI provides **3 hooks** across two configuration systems:
+Codex CLI provides **5 hooks** via hooks.json:
 
 | # | Hook | Event Type | Config File | Description |
 |:-:|------|------------|-------------|-------------|
-| 1 | `agent-turn-complete` | `agent-turn-complete` | `config.toml` | Runs when the Codex agent finishes responding |
+| 1 | `SessionStart` | `SessionStart` | `hooks.json` | Runs once at session start — injects context + plays sound |
-| 2 | `SessionStart` | `SessionStart` | `hooks.json` | Runs once at session start — injects context + plays sound |
+| 2 | `PreToolUse` | `PreToolUse` | `hooks.json` | Runs before a tool executes — plays sound |
-| 3 | `Stop` | `stop` | `hooks.json` | Runs when the session ends — plays sound |
+| 3 | `PostToolUse` | `PostToolUse` | `hooks.json` | Runs after a tool completes — plays sound |
+| 4 | `Stop` | `stop` | `hooks.json` | Runs when the session ends — plays sound |
+| 5 | `UserPromptSubmit` | `UserPromptSubmit` | `hooks.json` | Runs when the user submits a prompt — plays sound |
 
-> Hooks 2 and 3 require **Codex CLI v0.114.0+** with the hooks engine enabled:
+> Hooks 1 and 4 require **Codex CLI v0.114.0+** with the hooks engine enabled.
+> Hooks 2 and 3 require **Codex CLI v0.117.0+** with the hooks engine enabled.
+> Hook 5 requires **Codex CLI v0.116.0+** with the hooks engine enabled:
 > ```bash
 > codex -c features.codex_hooks=true
 > ```
 
 ### How Hooks Are Called
 
-**agent-turn-complete hook** (config.toml) — JSON passed as CLI argument:
+All hooks (hooks.json) are called with `--hook` flag:
-```
-python3 .codex/hooks/scripts/hooks.py '{"type":"agent-turn-complete"}'
-```
-
-**SessionStart / Stop hooks** (hooks.json) — called with `--hook` flag:
 ```
 python3 .codex/hooks/scripts/hooks.py --hook SessionStart
+python3 .codex/hooks/scripts/hooks.py --hook PreToolUse
+python3 .codex/hooks/scripts/hooks.py --hook PostToolUse
 python3 .codex/hooks/scripts/hooks.py --hook Stop
+python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit
 ```
 
 ### SessionStart Context Injection
@@ -37,8 +39,6 @@ The SessionStart hook outputs context to **stdout**, which feeds directly into t
 - Working tree status (clean or uncommitted changes)
 - Working directory path
 
-> **Key difference from Claude Code:** Claude Code passes JSON via **stdin**, while Codex CLI passes it as a **CLI argument**. The new hooks.json system uses `--hook` flags.
-
 ## Prerequisites
 
 Before using hooks, ensure you have **Python 3** installed on your system.
@@ -64,19 +64,12 @@ The hook script automatically detects and uses the appropriate audio player for
 
 ### Configuration Files
 
-There are **three** configuration files:
+There are **two** configuration files:
 
-1. **`.codex/config.toml`** — Registers the `agent-turn-complete` hook (via `notify`)
+1. **`.codex/hooks.json`** — Registers `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, and `UserPromptSubmit` hooks
-2. **`.codex/hooks.json`** — Registers `SessionStart` and `Stop` hooks (v0.114.0+)
+2. **`.codex/hooks/config/hooks-config.json`** — Enable/disable individual hooks and logging
-3. **`.codex/hooks/config/hooks-config.json`** — Enable/disable individual hooks and logging
 
-#### config.toml (agent-turn-complete hook)
+#### hooks.json
-
-```toml
-notify = ["python3", ".codex/hooks/scripts/hooks.py"]
-```
-
-#### hooks.json (SessionStart + Stop hooks)
 
 ```json
 {
@@ -89,6 +82,22 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"]
         "timeout": 10
       }
     ],
+    "PreToolUse": [
+      {
+        "type": "shell",
+        "command": "python3 .codex/hooks/scripts/hooks.py --hook PreToolUse",
+        "statusMessage": "Running pre-tool-use hook...",
+        "timeout": 10
+      }
+    ],
+    "PostToolUse": [
+      {
+        "type": "shell",
+        "command": "python3 .codex/hooks/scripts/hooks.py --hook PostToolUse",
+        "statusMessage": "Running post-tool-use hook...",
+        "timeout": 10
+      }
+    ],
     "Stop": [
       {
         "type": "shell",
@@ -96,6 +105,14 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"]
         "statusMessage": "Running session stop hook...",
         "timeout": 10
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "shell",
+        "command": "python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit",
+        "statusMessage": "Running user prompt submit hook...",
+        "timeout": 10
+      }
     ]
   }
 }
@@ -108,17 +125,21 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"]
 Edit `.codex/hooks/config/hooks-config.json`:
 ```json
 {
-  "disableAgentTurnCompleteHook": false,
   "disableSessionStartHook": false,
+  "disablePreToolUseHook": false,
+  "disablePostToolUseHook": false,
   "disableStopHook": false,
+  "disableUserPromptSubmitHook": false,
   "disableLogging": true
 }
 ```
 
 **Configuration Options:**
-- `disableAgentTurnCompleteHook`: Set to `true` to disable the agent-turn-complete sound
 - `disableSessionStartHook`: Set to `true` to disable the session start context injection and sound
+- `disablePreToolUseHook`: Set to `true` to disable the pre-tool-use sound
+- `disablePostToolUseHook`: Set to `true` to disable the post-tool-use sound
 - `disableStopHook`: Set to `true` to disable the session stop sound
+- `disableUserPromptSubmitHook`: Set to `true` to disable the user prompt submit sound
 - `disableLogging`: Set to `true` to disable logging hook events to `.codex/hooks/logs/hooks-log.jsonl`
 
 ### Configuration Fallback
@@ -136,9 +157,11 @@ Create or edit `.codex/hooks/config/hooks-config.local.json` for personal prefer
 
 ```json
 {
-  "disableAgentTurnCompleteHook": true,
   "disableSessionStartHook": false,
+  "disablePreToolUseHook": false,
+  "disablePostToolUseHook": false,
   "disableStopHook": true,
+  "disableUserPromptSubmitHook": false,
   "disableLogging": true
 }
 ```
@@ -154,6 +177,11 @@ Run the test suite:
 python3 -m unittest tests.test_hooks -v
 ```
 
+## Voice
+
+website used to generate sounds: https://elevenlabs.io/
+voice used: Adam - American, Dark and Tough
+
 ## Future Extensibility
 
 This project can be extended by: