fix: capture Codex Plan Review transcripts

docs/demo/demo.md

@@ -93,7 +93,7 @@ graph TB
         CLIPBOARD["System Clipboard"]
     end
 
-    CODEX -->|"notify hook"| CLI
+    CODEX -->|"notify arg / Stop stdin"| CLI
     CLAUDE -->|"Stop hook (stdin)"| CLI
     GEMINI -->|"AfterAgent hook (stdin)"| CLI
 
@@ -171,7 +171,7 @@ Each supported AI agent has a unique hook mechanism. cliV normalizes these into
 
 | Agent | Hook Type | Trigger | Data Source | Cache Key |
 |:---|:---|:---|:---|:---|
-| Codex | `notify` | `agent-turn-complete` | CLI argument (JSON) | PID cache key + sidecar thread metadata |
+| Codex | `notify` + `Stop` | completed turn / lifecycle stop | CLI argument + stdin (JSON) | PID cache key + sidecar thread metadata |
 | Claude Code | `Stop` | `Stop` event | stdin (JSON) | `session_id` + PID |
 | Gemini CLI | `AfterAgent` | After agent response | stdin (JSON) | `GEMINI_SESSION_ID` + PID |
 
@@ -183,6 +183,29 @@ Each supported AI agent has a unique hook mechanism. cliV normalizes these into
 notify = ["cliv", "cache-codex"]
 ```
 
+Add a user-level `Stop` hook in `~/.codex/hooks.json` for Plan Review, then review it through `/hooks`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex's Plan decision dialog currently owns keyboard input. Choose No to return to the normal composer before pressing `Ctrl+G`; cliV then opens the plan captured by the Stop hook.
+
 **Claude Code** — Add to `~/.claude/settings.json`:
 
 ```json
@@ -233,7 +256,7 @@ cliV uses a hand-rolled CLI parser (no external crate dependencies) to keep the
 flowchart TD
     START["cliV invoked"] --> CHECK_SUB{"argv[1] is<br/>subcommand?"}
 
-    CHECK_SUB -->|"cache-codex"| CODEX_CACHE["CacheCodex Mode<br/>Parse JSON arg"]
+    CHECK_SUB -->|"cache-codex"| CODEX_CACHE["CacheCodex Mode<br/>Parse argv or stdin JSON"]
     CHECK_SUB -->|"cache-claude"| CLAUDE_CACHE["CacheClaude Mode<br/>Read stdin"]
     CHECK_SUB -->|"cache-gemini"| GEMINI_CACHE["CacheGemini Mode<br/>Read stdin"]
     CHECK_SUB -->|"No"| GUI_MODE["GUI Mode"]
@@ -261,8 +284,8 @@ flowchart TD
 pub enum CliMode {
     /// Launch the Tauri GUI (default).
     Gui,
-    /// Cache a Codex reply from notify hook: `cliv cache-codex '<json>'`
-    CacheCodex(String),
+    /// Cache a Codex reply from notify argv or Stop-hook stdin.
+    CacheCodex(Option<String>),
     /// Cache a Claude reply from Stop hook (stdin): `cliv cache-claude`
     CacheClaude,
     /// Cache a Gemini reply from AfterAgent hook (stdin): `cliv cache-gemini`
@@ -1262,7 +1285,8 @@ graph TB
 cliv document.md
 
 # Cache an agent reply (called by hooks, not users)
-cliv cache-codex '<json>'
+cliv cache-codex '<json>'  # notify payload from argv
+cliv cache-codex           # Stop-hook payload from stdin
 cliv cache-claude          # reads from stdin
 cliv cache-gemini          # reads from stdin
 
@@ -1292,7 +1316,7 @@ mindmap
       serde_json
       dirs crate
     Integration
-      Codex notify hook
+      Codex notify + Stop hooks
       Claude Stop hook
       Gemini AfterAgent hook
     Storage

docs/demo/overview-and-quickstart.md

@@ -107,6 +107,31 @@ On macOS, if `cliv` is not in PATH, use:
 notify = ["/Applications/cliV.app/Contents/MacOS/cliv", "cache-codex"]
 ```
 
+Keep notify for compatibility, and create `~/.codex/hooks.json` to capture Plan Review content:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Use `/hooks` in Codex to review and trust the command. If inline hooks already exist in `config.toml`, merge the Stop handler there instead of maintaining both hook formats. On macOS without a symlink, use the full cliV executable path in `command` too.
+
+Codex's Plan decision dialog currently captures keyboard input, so `Ctrl+G` does not launch `$EDITOR` inside that dialog. Choose No to return to the normal composer, then press `Ctrl+G`; cliV will load the plan captured by the Stop hook.
+
 #### Claude Code
 
 Edit `~/.claude/settings.json` and merge this into your existing config:

docs/demo/overview-and-quickstart.zh-CN.md

@@ -107,6 +107,31 @@ notify = ["cliv", "cache-codex"]
 notify = ["/Applications/cliV.app/Contents/MacOS/cliv", "cache-codex"]
 ```
 
+保留 notify 用于兼容，并创建 `~/.codex/hooks.json` 来捕获 Plan Review 内容：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+在 Codex 中使用 `/hooks` 审核并信任该命令。如果 `config.toml` 已经有 inline Hooks，请把 Stop handler 合并进去，不要同时维护两种 Hook 格式。macOS 未创建软链接时，`command` 也要使用 cliV 的完整可执行路径。
+
+Codex 的 Plan 决策弹窗当前会接管键盘输入，因此在弹窗内按 `Ctrl+G` 不会启动 `$EDITOR`。选择 No 回到普通输入框后再按 `Ctrl+G`，cliV 会加载 Stop Hook 已捕获的计划。
+
 #### Claude Code
 
 编辑 `~/.claude/settings.json`，把下面内容合并进现有配置：

docs/install-guide.md

@@ -96,7 +96,7 @@ setx EDITOR cliv
 
 Then open a new terminal.
 
-When an agent triggers `Ctrl+G`, it launches `$EDITOR`. That is how cliV opens from the CLI workflow.
+When an agent triggers `Ctrl+G` from its normal composer, it launches `$EDITOR`. Codex's Plan decision dialog currently owns keyboard input, so return to the composer before using this shortcut.
 
 ## 3. Configure Agent Hooks
 
@@ -111,6 +111,29 @@ Edit `~/.codex/config.toml`:
 notify = ["cliv", "cache-codex"]
 ```
 
+`notify` keeps compatibility with ordinary completed turns. To capture plans when Codex enters Plan Review, also create `~/.codex/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Open `/hooks` in Codex and trust this hook before testing it. Codex skips new or changed command hooks until they are reviewed. If you already define inline Codex hooks in `config.toml`, merge this `Stop` handler there instead of configuring both representations. On macOS without a symlink, replace the command with `/Applications/cliV.app/Contents/MacOS/cliv cache-codex`.
+
 ### Claude Code
 
 Edit `~/.claude/settings.json`:

docs/install-guide.zh-CN.md

@@ -96,7 +96,7 @@ setx EDITOR cliv
 
 然后重新打开一个新的终端。
 
-当 Agent 触发 `Ctrl+G` 时，它会启动 `$EDITOR`，这就是 cliV 被唤起的入口。
+在 Agent 的普通输入框中触发 `Ctrl+G` 时，它会启动 `$EDITOR`。Codex 的 Plan 决策弹窗当前会接管键盘输入，因此需要先回到输入框再使用该快捷键。
 
 ## 3. 配置 Agent Hook
 
@@ -111,6 +111,29 @@ setx EDITOR cliv
 notify = ["cliv", "cache-codex"]
 ```
 
+`notify` 继续兼容普通已完成回合。为了在 Codex 进入 Plan Review 时捕获计划，还要创建 `~/.codex/hooks.json`：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+测试前请在 Codex 中打开 `/hooks` 并信任该 Hook；新的或发生变化的 command Hook 在完成审核前会被跳过。如果你已经在 `config.toml` 中使用 inline Codex Hooks，请把这个 `Stop` handler 合并到现有配置，不要同时维护两种表示。macOS 未创建软链接时，把 command 改为 `/Applications/cliV.app/Contents/MacOS/cliv cache-codex`。
+
 ### Claude Code
 
 编辑 `~/.claude/settings.json`：

docs/integrations.md

@@ -87,6 +87,31 @@ notify = ["/Applications/cliV.app/Contents/MacOS/cliv", "cache-codex"]
 
 Codex passes JSON as a command-line argument to `cliv cache-codex`.
 
+Keep that notify entry for compatibility, then add `~/.codex/hooks.json` so Plan Review replies are delivered through stdin:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Current Codex Plan Review builds may leave both assistant-message fields null. In that case cliV reads only the same-session, same-turn `item_completed/Plan` entry from the `transcript_path` supplied by the Stop hook; no additional user command is required.
+
+Review and trust the command through `/hooks` in Codex. If the same config layer already uses inline hooks, merge this handler there rather than keeping both inline hooks and `hooks.json`. On macOS without a symlink, use `/Applications/cliV.app/Contents/MacOS/cliv cache-codex` as the command.
+
 ### Claude Code
 
 `~/.claude/settings.json`:
@@ -210,6 +235,9 @@ Codex:
 ```bash
 CODEX_THREAD_ID=424242 cliv cache-codex '{"type":"agent-turn-complete","thread-id":"test-123","last-assistant-message":"# Hello\nTest reply."}'
 cat ~/.codex/reply_cache/424242.md
+
+printf '%s' '{"hook_event_name":"Stop","session_id":"test-123","turn_id":"plan-1","permission_mode":"plan","last_assistant_message":"<proposed_plan>\n# Plan\n\n- Review this\n</proposed_plan>"}' | CODEX_THREAD_ID=424242 cliv cache-codex
+cat ~/.codex/reply_cache/424242.md
 ```
 
 Claude Code:
@@ -230,6 +258,8 @@ If these commands write the expected `.md` files, cliV itself is working and the
 
 - the wrong hook file path
 - malformed hook JSON or TOML
+- a Codex Stop hook that has not been trusted through `/hooks`
+- Codex hooks disabled through the `features.hooks` setting
 - a shell quoting issue
 - a stale terminal session that has not reloaded `PATH` or `EDITOR`
 
@@ -241,4 +271,5 @@ Check these in order:
 2. Did the hook actually write a cache file under `~/.codex`, `~/.claude`, or `~/.gemini`?
 3. Is the lookup key the one cliV is expecting for that launch context?
 4. Did a non-default path or shell quoting issue stop the hook from running?
-5. On Windows, did you reopen the terminal after install or after changing `EDITOR`?
+5. For Codex Plan Review, is the Stop hook listed as trusted under `/hooks`?
+6. On Windows, did you reopen the terminal after install or after changing `EDITOR`?

docs/integrations.zh-CN.md

@@ -87,6 +87,31 @@ notify = ["/Applications/cliV.app/Contents/MacOS/cliv", "cache-codex"]
 
 Codex 会把 JSON 作为命令行参数传给 `cliv cache-codex`。
 
+保留该 notify 配置用于兼容，再添加 `~/.codex/hooks.json`，让 Plan Review 回复通过 stdin 传入：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cliv cache-codex",
+            "timeout": 5,
+            "statusMessage": "Caching reply for cliV"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+当前 Codex 的 Plan Review 可能让两个 assistant-message 字段都为 `null`。此时 cliV 只读取 Stop Hook 提供的 `transcript_path` 中同 session、同 turn 的 `item_completed/Plan` 条目；用户不需要执行额外命令。
+
+请在 Codex 中通过 `/hooks` 审核并信任该命令。如果同一个配置层已经使用 inline Hooks，请把这个 handler 合并进去，不要同时保留 inline Hooks 和 `hooks.json`。macOS 未创建软链接时，command 使用 `/Applications/cliV.app/Contents/MacOS/cliv cache-codex`。
+
 ### Claude Code
 
 `~/.claude/settings.json`：
@@ -210,6 +235,9 @@ Codex：
 ```bash
 CODEX_THREAD_ID=424242 cliv cache-codex '{"type":"agent-turn-complete","thread-id":"test-123","last-assistant-message":"# Hello\nTest reply."}'
 cat ~/.codex/reply_cache/424242.md
+
+printf '%s' '{"hook_event_name":"Stop","session_id":"test-123","turn_id":"plan-1","permission_mode":"plan","last_assistant_message":"<proposed_plan>\n# Plan\n\n- Review this\n</proposed_plan>"}' | CODEX_THREAD_ID=424242 cliv cache-codex
+cat ~/.codex/reply_cache/424242.md
 ```
 
 Claude Code：
@@ -230,6 +258,8 @@ cat ~/.gemini/reply_cache/test-gemini.md
 
 - hook 文件路径写错了
 - JSON / TOML 语法有误
+- Codex Stop Hook 尚未通过 `/hooks` 信任
+- Codex 的 `features.hooks` 设置禁用了 Hooks
 - shell 引号转义不对
 - 终端仍然是旧会话，没有重新加载 `PATH` 或 `EDITOR`
 
@@ -241,4 +271,5 @@ cat ~/.gemini/reply_cache/test-gemini.md
 2. 对应 `~/.codex`、`~/.claude`、`~/.gemini` 下是否真的写出了 cache 文件？
 3. 当前启动上下文里，cliV 查找的 lookup key 是否和你预期一致？
 4. 是否因为非默认路径或 shell 引号问题，导致 hook 根本没执行？
-5. Windows 上是否在安装或修改 `EDITOR` 之后重新打开了终端？
+5. Codex Plan Review 场景下，`/hooks` 是否显示 Stop Hook 已受信任？
+6. Windows 上是否在安装或修改 `EDITOR` 之后重新打开了终端？

docs/regression-cases.md

@@ -115,6 +115,18 @@
 
 ---
 
+## Agent Reply Capture
+
+### ARC-001 — Codex Plan Review 应显示当前计划而不是空白或上一轮回复
+- **Area:** agent-integration
+- **Scenario:** Codex 同一会话先完成普通回复，随后在 Plan 模式产生 `last_assistant_message: null`，计划仅存在于同 session、同 turn 的 transcript `item_completed/Plan` 事件中；在 Plan 决策弹窗选择 No 回到普通输入框后，再通过 `$EDITOR` 调起 cliV
+- **Expected:** cliV 显示当前计划的 Markdown 内容，外层 transport tags 不可见；提交批注后内容写回 Codex 提供的临时 target
+- **Coverage:** manual
+- **Manual verification:** 在 `~/.codex/config.toml` 保留 notify，并在 `~/.codex/hooks.json` 配置、通过 `/hooks` 信任 `Stop -> cliv cache-codex`；重开 Codex，先完成一个普通回合，再进入 Plan 模式生成计划；在 Plan 决策弹窗选择 No 回到普通输入框，按 `Ctrl+G` 调起 cliV；确认显示的是当前计划，完成一条批注并验证 Codex 收到写回内容
+- **Reason:** null-message transcript fallback、双 transport、PID 覆盖和 extractor 回读已有 Rust 自动化；真实 Codex TUI 的 Plan Review、Hook trust 与外部 `$EDITOR` 交接需要安装态 Codex 进行跨进程人工验证
+
+---
+
 ## Worktree Tooling
 
 ### WT-001 — shared-cache helper 不得让默认 Rust 安装失效

openspec/changes/archive/2026-08-11-capture-codex-plan-review/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-11