devlog-tracker 0.33.5 → 0.34.0

package/README.md

@@ -2,7 +2,7 @@
 
 *English | [繁體中文](README.zh-TW.md)*
 
-**Version** 0.33.5
+**Version** 0.34.0
 
 Maintains a `.devlog/devlog.md` in your project, turning each conversation round's requests, decisions, and outcomes into a permanent record. A conversation disappears the moment you `/clear` or switch sessions; this file fills that gap so work can pause and resume. Nothing is touched until you explicitly run `/devlog-tracker:start` — installing the plugin alone doesn't create or modify any files.
 
@@ -45,19 +45,43 @@ Merges the hooks into `.claude/settings.local.json` (not `settings.json` — the
 
 ### Codex
 
+**Option 1: plugin marketplace**
+
+To try an unpublished checkout, run these commands **from this repository's root**:
+
+```bash
+codex plugin marketplace add .
+codex plugin add devlog-tracker@devlog-tracker
+```
+
+After the branch is merged and pushed, install from GitHub instead:
+
+```bash
+codex plugin marketplace add gogogohuang/devlog-tracker
+codex plugin add devlog-tracker@devlog-tracker
+```
+
+Start a new Codex session in the project you want to track, review and trust the bundled hooks with `/hooks`, then use `$devlog-start` (or pick it from `/skills`). The plugin keeps its scripts in Codex's plugin cache; it does not create a `.devlog-tracker/` directory in each project. Tracking data is created under `.devlog/` only after `$devlog-start`. If this project already uses `npx devlog-tracker init --codex`, remove the devlog-tracker entries from its project-level `.codex/hooks.json` before enabling the plugin to avoid running each hook twice.
+
+**Option 2: npx (vendored into the project, version pinnable)**
+
 ```bash
 npx devlog-tracker init --codex
 ```
 
 Merges the `hooks` from `codex/hooks.json` into the project's `.codex/hooks.json`, and generates `.agents/skills/devlog-<name>/SKILL.md` from `commands/*.md`, invoked with `$devlog-<name>` (or picked from `/skills`); it also adds the same kind of fallback block to `AGENTS.md`. Files the older 0.25.0 version wrote to `.codex/prompts/` are cleared out on the next `init` run — Codex doesn't read project-level custom prompts.
 
-**Hooks require approval before they run.** Codex requires approval for new or changed hooks; an unapproved hook is silently skipped — **with no warning at all**, so it looks like devlog just isn't recording. This is independent of whether the project is set to `trust_level = "trusted"`; project trust doesn't make hooks active.
+**Hooks require trust review before they run.** Codex skips new or changed hooks until you trust their current definitions. For npx installs, the project `.codex/` layer must also be trusted to load project hooks. Use `/hooks` to review the active definitions.
 
-- Interactive mode: the first time you open it, Codex prompts that hooks need approval; they only run once approved. A later change to hook configuration (e.g. re-running `init` and changing paths or commands) may require approval again.
+- Interactive mode: Codex warns at startup when hooks need review. Use `/hooks` to inspect and trust them. A later change to hook configuration (e.g. re-running `init` and changing paths or commands) may require another review.
 - Non-interactive `codex exec` (CI, scripts): unapproved hooks are silently skipped. `--dangerously-bypass-hook-trust` lets them run, but that flag skips trust checks for *all* hooks, so it's only appropriate for automation environments where you've already vetted the hook sources yourself.
 - To confirm it's working: after `start`, send a message and check whether `.devlog/.round-current.md` shows this round's User Input skeleton; if not, the hook didn't run.
 
-Codex currently has no equivalent to "user interrupted" (Claude Code's `PostToolUseFailure`/`is_interrupt`) or "this round ended abnormally" (`StopFailure`); these two detailed states won't be marked `INTERRUPTED` on Codex, but the core enforcement mechanism (the `Stop` event blocking unfinished rounds) is unaffected.
+When the silence or workspace guard blocks a tool, Codex can read the current round with a single `cat <project>/.devlog/.round-current.md` command and update it with `apply_patch`. The block message includes the project path.
+
+Codex's `Interrupt` hook records an interrupted main-thread turn as `INTERRUPTED`. Codex has no `StopFailure` event for other abnormal endings; an open round is recovered on the next prompt or session start, or when `SessionEnd` runs. Codex's `SessionEnd` reason is currently only `other`, and it may run after an idle session rather than immediately when you switch conversations. The `Stop` hook still enforces completion of normal turns. Codex can also start from a subdirectory of an installed project; the hooks find the installation root.
+
+With Lessons Mode enabled, Codex's `SubagentStart` hook gives subagents the recording guidance and project path. For npx installs, it preserves the main project's path when a subagent runs in a separate worktree; plugin installs use that worktree's path.
 
 ### Cursor
 
@@ -77,6 +101,8 @@ Without `--claude`/`--codex`/`--cursor`, it interactively asks which platform(s)
 
 Copies `core/scripts/`, `claude/hooks.json`, `codex/hooks/`, `cursor/hooks/`, `skills/`, and `commands/` into the project's `.devlog-tracker/`. Re-running `npx devlog-tracker init` upgrades to the package's current version; `npx devlog-tracker status` checks whether the installed version is behind. `npx devlog-tracker report [--json] [--all-branches]` and `npx devlog-tracker timeline [--all-branches] [--out <path>]` run the same scripts as `/devlog-tracker:report` and `/devlog-tracker:timeline`, using the vendored copy when there is one.
 
+`.devlog-tracker/` contains the installed program. `.devlog/` contains your project's tracking data and is created only when you run the start command. Therefore, seeing `.devlog-tracker/` immediately after `npx init` is expected; `init` alone does not start recording.
+
 `init` writes this machine's absolute paths into each platform's hooks config and into `.devlog-tracker/env.sh`. If you commit these files to git, each teammate needs to run `npx devlog-tracker init` on their own machine (paths differ per machine); alternatively, add `.devlog-tracker/` and the generated hooks config files to `.gitignore`.
 
 To install manually (without npx), set `DEVLOG_TRACKER_ROOT` to this plugin's absolute path, and merge the `hooks` from the matching platform's `hooks.json` into the project config; `commands/*.md` prefers `DEVLOG_TRACKER_ROOT`, falling back to `CLAUDE_PLUGIN_ROOT`:
@@ -100,19 +126,20 @@ Run once in your project (pick whichever matches your install method):
 ```
 /devlog-tracker:start   # Claude Code plugin
 /devlog-start           # npx init --claude
-$devlog-start           # npx init --codex
+$devlog-start           # Codex plugin or npx init --codex
 ```
 
 After that, just converse normally — every round is enforced-checked and `.devlog/devlog.md` gets updated before it can end. After `/clear`, context is empty; to pick up prior work, run the matching `continue` command. See the command table below for pause, archive, named export, status, and span.
 
 ## Commands
 
-The table below uses the plugin's `/devlog-tracker:*` namespace; `npx init --claude` installs `/devlog-<name>`, and `npx init --codex` installs `$devlog-<name>` — the command content is the same.
+The table below uses the Claude plugin's `/devlog-tracker:*` namespace; `npx init --claude` installs `/devlog-<name>`, while either Codex installation method uses `$devlog-<name>` — the command content is the same.
 
 | Command | What it does |
 |---|---|
 | `/devlog-tracker:start` | Runs a script that creates `.devlog/.enabled` (missing state files are backfilled; existing thresholds aren't reset). Reads the file to check progress; doesn't auto-start work. `.devlog/` contains a prompt suggesting adding it to `.gitignore`, and only edits it with your consent. |
 | `/devlog-tracker:continue` | Reads `.devlog/devlog.md`, checks the last round's Handoff "Workspace" section, then continues per its next step. Use this after `/clear` to resume. See [`docs/design/continue.md`](docs/design/continue.md). |
+| `/devlog-tracker:migrate` | Converts legacy `####` Handoff/Session Handoff in `devlog.md`, branch files, the open round and `handoff.md` to XML (backups as `*.pre-migrate`). The Stop hook tells the agent to run it when it blocks a legacy Handoff. |
 | `/devlog-tracker:pause` | Pauses enforced recording; history files are untouched, and you can `start` again later. |
 | `/devlog-tracker:compact` | A script moves older `DONE` rounds into `devlog.archive.md` (Checkpoints and unfinished rounds stay in the main file). |
 | `/devlog-tracker:keep` | Scans the current branch's main file (to reorganize every devlog at once, use `keep-all`), groups it by topic, lists suggestions at once, then — after confirmation — moves each section out into its own `devlog.<name>.md` (leaving a `## Kept index` pointer line with a one-sentence topic description in the main file); can also extract a single section or merge everything into one history file. Not the same as compact. See [`docs/design/keep.md`](docs/design/keep.md). |
@@ -170,20 +197,24 @@ Every round has these fixed sections:
 - **`User Input`** — the raw submitted text takes priority (written by the hook; Claude shouldn't rewrite it), common tokens are masked
 - **`Summary`** — a conclusion a human can scan
 - **`Reply`** — what was said/promised to the user this round
-- **`Handoff`** — for the next round to pick up (decisions / files / workspace / current state / completion criteria / next steps)
+- **`Handoff`** — for the next round to pick up (decisions / files / workspace / current state / completion criteria / next steps). `Handoff` and `Session Handoff` are written as line-based XML tags (`<handoff>` … `<next>` …) because only the next agent and the Stop hook read them; `Summary`/`Reply` stay Markdown for humans. See [`docs/design/handoff-xml.md`](docs/design/handoff-xml.md).
 - **`Status`** — one of `DONE` / `IN_PROGRESS` / `BLOCKED` / `INTERRUPTED`
 
 "Workspace" is a git snapshot taken at wrap-up time; required whenever in progress or blocked. `DONE` also requires it if "Files" has content (claiming files were touched/committed). "Completion criteria" is required whenever in progress or blocked.
 
 The Stop hook does the following:
 
-1. Confirms `Summary`/`Reply`/`Handoff` headings have content underneath, and Status is one of the four values above; Handoff subsections must be in the order Decisions → Files → Workspace → Current state → Completion criteria → Next steps
+1. Confirms `Summary`/`Reply`/`Handoff` headings have content underneath, and Status is one of the four values above; Handoff must use the XML tag form, with tags in the order `decisions` → `files` → `workspace` → `state` → `done-when` → `next`
 2. In-progress/blocked rounds must have "Completion criteria" and "Next steps"; "Next steps" can't be pure blacklisted filler (e.g. a section that just says "continue finishing up" — string matching, not semantic scoring; see [`docs/design/next-step-blacklist.md`](docs/design/next-step-blacklist.md)); in-progress rounds get an additional lightweight actionability check; blocked rounds require "Current state" or "Next steps" to contain a missing-piece phrasing
 3. Machine-verifies that "Workspace" matches the actual git state at wrap-up time, verbatim (always checked when in progress/blocked; only checked for `DONE` when "Files" is non-empty) — this catches claims like "already committed" that don't actually match reality
 
-When `#### Files` is non-empty, it's likewise machine-verified: the commit section must match that commit's actual content verbatim; for uncommitted sections, it only requires that the claimed paths actually have changes (not full coverage, so leftovers from a previous round aren't counted as missing from this one).
+When `<files>` is non-empty, it's likewise machine-verified: the commit section must match that commit's actual content verbatim; for uncommitted sections, it only requires that the claimed paths actually have changes (not full coverage, so leftovers from a previous round aren't counted as missing from this one).
+
+See [`docs/design/summary-handoff.md`](docs/design/summary-handoff.md), [`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md), [`docs/design/files-verify.md`](docs/design/files-verify.md), [`docs/design/handoff-xml.md`](docs/design/handoff-xml.md), and SKILL.md for details.
+
+### Upgrading to XML Handoff
 
-See [`docs/design/summary-handoff.md`](docs/design/summary-handoff.md), [`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md), [`docs/design/files-verify.md`](docs/design/files-verify.md), and SKILL.md for details.
+Rounds written before this change are in the legacy `####`-headed form and are still read fine. Archive, keep and lessons files (`devlog.archive.md`, `devlog.<name>.md`, `devlog.lessons.*.md`) are never rewritten. When the Stop hook blocks on a legacy Handoff in the round it's checking, it tells the agent to run the migrate command (`/devlog-tracker:migrate` on the Claude plugin or `$devlog-migrate` on Codex; underlying script: `migrate-handoff.sh`) itself, then finish the turn again — no action needed from you in the common case. Migrate rewrites `devlog.md`, the branch devlog files, the open round (`.round-current.md`) and `handoff.md`／`handoff.<branch>.md` in place, leaving a `*.pre-migrate` backup next to each file it changes; a round it cannot map exactly is left as-is and listed on a `SKIP` line. If the agent keeps writing the legacy form instead of picking up the fix, update the plugin or rerun `npx devlog-tracker init`, then use the start command for your installation (`/devlog-tracker:start` on the Claude plugin or `$devlog-start` on Codex).
 
 ## What the hooks do automatically
 

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 *[English](README.md) | 繁體中文*
 
-**版本** 0.33.5
+**版本** 0.34.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -45,19 +45,43 @@ npx devlog-tracker init --claude
 
 ### Codex
 
+**方式一：plugin marketplace**
+
+要測試尚未發布的 checkout，先在**這個 repo 的根目錄**用本機版本安裝：
+
+```bash
+codex plugin marketplace add .
+codex plugin add devlog-tracker@devlog-tracker
+```
+
+合併並推送後，才改用 GitHub 來源安裝：
+
+```bash
+codex plugin marketplace add gogogohuang/devlog-tracker
+codex plugin add devlog-tracker@devlog-tracker
+```
+
+在要追蹤的專案開新 Codex session，用 `/hooks` 審核並信任 plugin 附帶的 hooks，再執行 `$devlog-start`（或從 `/skills` 選）。plugin 腳本放在 Codex 的快取中，不會在每個專案建立 `.devlog-tracker/`；執行 `$devlog-start` 後才會在專案建立 `.devlog/` 紀錄資料。若專案之前跑過 `npx devlog-tracker init --codex`，啟用 plugin 前先從專案的 `.codex/hooks.json` 移除 devlog-tracker 的 hook 項目，避免同一個 hook 執行兩次。
+
+**方式二：npx（vendor 進專案，版本可鎖定）**
+
 ```bash
 npx devlog-tracker init --codex
 ```
 
 會把 `codex/hooks.json` 的 `hooks` 合併進專案 `.codex/hooks.json`，並從 `commands/*.md` 產生 `.agents/skills/devlog-<名稱>/SKILL.md`，用 `$devlog-<名稱>`（或 `/skills` 選）執行；同時在 `AGENTS.md` 加上同一種 fallback 說明區塊。舊版（0.25.0）寫到 `.codex/prompts/` 的檔案會在重跑 `init` 時清掉——Codex 不讀專案層級的 custom prompts。
 
-**hook 需要審核才會執行。** Codex 對新增或有變動的 hook 要求先審核；沒核准的 hook 會被直接略過，而且**沒有任何警告**，看起來就像 devlog 沒在記錄。這跟專案有沒有設成 `trust_level = "trusted"` 是兩回事，專案信任不會讓 hook 生效。
+**hook 需要信任審核才會執行。** Codex 會略過尚未信任的新 hook 或變更過的 hook。若使用 npx 安裝，專案的 `.codex/` 設定層也須先被信任，專案 hook 才會載入；之後可用 `/hooks` 查看哪些 hook 定義仍待審核。
 
-- 互動模式：第一次開啟時 Codex 會提示有 hook 需要審核，核准後才會執行。之後 hook 的設定有變動（例如重跑 `init` 讓路徑或指令改變）也可能要再核准一次。
+- 互動模式：有 hook 待審核時，Codex 啟動時會顯示警告。用 `/hooks` 檢查並信任它們。之後 hook 的設定有變動（例如重跑 `init` 讓路徑或指令改變）也可能要再審核一次。
 - 非互動的 `codex exec`（CI、腳本）：未審核的 hook 會被靜默略過。`--dangerously-bypass-hook-trust` 可以讓它們跑起來，但那個旗標會略過所有 hook 的信任檢查，只適合已經自己確認過 hook 來源的自動化環境。
 - 想確認有沒有生效：`start` 之後送一則訊息，看 `.devlog/.round-current.md` 有沒有出現這一輪的 User Input skeleton；沒有就代表 hook 沒被執行。
 
-Codex 目前沒有對應「使用者中斷」（Claude Code 的 `PostToolUseFailure`／`is_interrupt`）與「這輪異常結束」（`StopFailure`）的事件，這兩種細節狀態在 Codex 上不會被標記成 `INTERRUPTED`；核心強制記錄機制（`Stop` 事件擋住未寫完的輪次）不受影響。
+沉默或工作區檢查擋住工具時，Codex 可用單一 `cat <專案>/.devlog/.round-current.md` 指令讀取當輪，再用 `apply_patch` 修改；封鎖訊息會附上專案路徑。
+
+Codex 的 `Interrupt` hook 會把主執行緒被中斷的輪次標成 `INTERRUPTED`。Codex 沒有處理其他異常結束的 `StopFailure` 事件；未收尾輪次會在下次訊息、下次 session start，或 `SessionEnd` 執行時補記。Codex 的 `SessionEnd` 原因目前只有 `other`，切換對話後也可能等閒置一段時間才觸發。正常輪次仍由 `Stop` hook 強制收尾。從已安裝專案的子目錄啟動 Codex 時，hook 也會找到安裝根目錄。
+
+Lessons Mode 開啟時，Codex 的 `SubagentStart` hook 會把記錄指引與專案路徑交給子代理。npx 安裝在子代理使用獨立 worktree 時仍會傳主專案路徑；plugin 安裝則使用該 worktree 的路徑。
 
 ### Cursor
 
@@ -77,6 +101,8 @@ npx devlog-tracker init
 
 會把 `core/scripts/`、`claude/hooks.json`、`codex/hooks/`、`cursor/hooks/`、`skills/`、`commands/` 複製進專案的 `.devlog-tracker/`。重新執行 `npx devlog-tracker init` 可以升級到套件目前的版本；`npx devlog-tracker status` 可以查目前裝的版本是否落後。`npx devlog-tracker report [--json] [--all-branches]` 和 `npx devlog-tracker timeline [--all-branches] [--out <路徑>]` 跑的是跟 `/devlog-tracker:report`、`/devlog-tracker:timeline` 同一支腳本，有 vendored 版本就用它。
 
+`.devlog-tracker/` 放的是安裝進專案的程式；`.devlog/` 放的是這個專案的紀錄資料，執行 start 指令後才會建立。因此 `npx init` 後先看到 `.devlog-tracker/` 是預期行為，單跑 `init` 不會開始記錄。
+
 `init` 會把這台機器專屬的絕對路徑寫進各平台的 hooks 設定檔與 `.devlog-tracker/env.sh`。如果你把這些檔案 commit 進 git，每位隊友都要在自己的機器上跑一次 `npx devlog-tracker init`（路徑每台機器不同）；或者改成把 `.devlog-tracker/` 與產生出來的 hooks 設定檔加進 `.gitignore`。
 
 若要手動裝（不透過 npx），設定 `DEVLOG_TRACKER_ROOT` 為本 plugin 的絕對路徑，把對應平台的 `hooks.json` 的 `hooks` 合併進專案設定；`commands/*.md` 會優先讀 `DEVLOG_TRACKER_ROOT`，否則讀 `CLAUDE_PLUGIN_ROOT`：
@@ -100,19 +126,20 @@ bash "$DEVLOG_TRACKER_ROOT/core/scripts/timeline-devlog.sh"
 ```
 /devlog-tracker:start   # Claude Code plugin
 /devlog-start           # npx init --claude
-$devlog-start           # npx init --codex
+$devlog-start           # Codex plugin 或 npx init --codex
 ```
 
 之後正常對話即可，每一輪結束前都會被強制檢查、補上 `.devlog/devlog.md` 的紀錄。`/clear` 之後 context 是空的；要接著做上一題，下對應的 `continue` 指令。暫停、歸檔、具名搬走、狀態與 span 見下方指令表。
 
 ## 指令
 
-下表以 plugin 的 `/devlog-tracker:*` namespace 表示；`npx init --claude` 裝的是 `/devlog-<名稱>`，`npx init --codex` 裝的是 `$devlog-<名稱>`，指令內容相同。
+下表以 Claude plugin 的 `/devlog-tracker:*` namespace 表示；`npx init --claude` 裝的是 `/devlog-<名稱>`，Codex 兩種安裝方式都用 `$devlog-<名稱>`，指令內容相同。
 
 | 指令 | 做什麼 |
 |---|---|
 | `/devlog-tracker:start` | 跑腳本建立 `.devlog/.enabled`（缺的 state 檔會補上，已有門檻不重置）。讀檔對進度，不自動開工。`.devlog/` 含 prompt，會建議加進 `.gitignore`，要你同意才改。 |
 | `/devlog-tracker:continue` | 讀 `.devlog/devlog.md`，核對最後一輪 Handoff「工作區」後再依下一步接著做。`/clear` 之後要接續用這個。細節見 [`docs/design/continue.md`](docs/design/continue.md)。 |
+| `/devlog-tracker:migrate` | 把 `devlog.md`、分支檔、開著的那一輪與 `handoff.md` 裡舊格式 `####` 的 Handoff／Session Handoff 轉成 XML（備份成 `*.pre-migrate`）。Stop hook 擋下舊格式的 Handoff 時，會叫 agent 自己跑這個指令。 |
 | `/devlog-tracker:pause` | 暫停強制記錄，歷史檔不動，之後可再 `start`。 |
 | `/devlog-tracker:compact` | 腳本把較舊的 `DONE` 輪次搬到 `devlog.archive.md`（Checkpoint 與未完成輪留在主檔）。 |
 | `/devlog-tracker:keep` | 掃目前分支的主檔分主題（要一次整理所有 devlog 用 `keep-all`），一次列出建議，確認後把各段各自搬走成 `devlog.<name>.md`（並在主檔留一個 `## Kept 索引` 指標行，含一句主題描述）；也可抽出一段或合併成全部歷史一檔。不是 compact。細節見 [`docs/design/keep.md`](docs/design/keep.md)。 |
@@ -170,20 +197,24 @@ sequenceDiagram
 - **`User Input`** — 送出原文優先（hook 寫入；Claude 不要改寫），常見 token 會遮罩
 - **`Summary`** — 給人掃的結論
 - **`Reply`** — 這輪對使用者說過／答應過的話
-- **`Handoff`** — 給下一輪接手（決策／檔案／工作區／現況／完成條件／下一步）
+- **`Handoff`** — 給下一輪接手（決策／檔案／工作區／現況／完成條件／下一步）。`Handoff` 與 `Session Handoff` 用以行為單位的 XML 標籤寫（`<handoff>` … `<next>` …），因為讀者只有下一輪的 agent 與 Stop hook；`Summary`／`Reply` 仍是給人看的 Markdown。細節見 [`docs/design/handoff-xml.md`](docs/design/handoff-xml.md)。
 - **`Status`** — `DONE` / `IN_PROGRESS` / `BLOCKED` / `INTERRUPTED` 四選一
 
 其中「工作區」是收尾時的 git 快照，進行中／卡住必寫；`DONE` 若「檔案」有內容（宣稱動過／commit 過檔案）也必寫。「完成條件」在進行中／卡住必寫。
 
 Stop hook 會做這些事：
 
-1. 確認 `Summary`／`Reply`／`Handoff` 標題底下有內容、Status 是上述四值之一；Handoff 小節順序為 決策 → 檔案 → 工作區 → 現況 → 完成條件 → 下一步
+1. 確認 `Summary`／`Reply`／`Handoff` 標題底下有內容、Status 是上述四值之一；Handoff 必須是 XML 標籤格式，標籤順序為 `decisions` → `files` → `workspace` → `state` → `done-when` → `next`
 2. 進行中／卡住時有「完成條件」與「下一步」；「下一步」不是純黑名單空話（例如整節只寫「繼續完成」；字串比對，非語意評分，細節見 [`docs/design/next-step-blacklist.md`](docs/design/next-step-blacklist.md)）；進行中另做輕量可執行檢查；卡住時「現況」或「下一步」須含缺件句式
 3. 機器核對「工作區」是否跟收尾當下的 git 狀態逐字相符（進行中／卡住一律核對，`DONE` 只在「檔案」非空時核對），避免「已 commit 完成」卻其實沒 commit 這類宣稱跟實際不符
 
-`#### 檔案` 非空時同樣機器核對：commit 區塊要跟該次 commit 的實際內容逐字相符，未 commit 的區塊只要求宣稱的路徑真的存在變更（不要求涵蓋全部，避免把跨輪殘留算成這輪漏列）。
+`<files>` 非空時同樣機器核對：commit 區塊要跟該次 commit 的實際內容逐字相符，未 commit 的區塊只要求宣稱的路徑真的存在變更（不要求涵蓋全部，避免把跨輪殘留算成這輪漏列）。
+
+細節見 [`docs/design/summary-handoff.md`](docs/design/summary-handoff.md)、[`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md)、[`docs/design/files-verify.md`](docs/design/files-verify.md)、[`docs/design/handoff-xml.md`](docs/design/handoff-xml.md) 和 SKILL.md。
+
+### 升級到 XML Handoff
 
-細節見 [`docs/design/summary-handoff.md`](docs/design/summary-handoff.md)、[`docs/design/devlog-as-ssot-assessment.md`](docs/design/devlog-as-ssot-assessment.md)、[`docs/design/files-verify.md`](docs/design/files-verify.md) 和 SKILL.md。
+舊輪次是 `####` 小節格式，讀取端照樣相容。archive、keep 與 lessons 檔（`devlog.archive.md`、`devlog.<name>.md`、`devlog.lessons.*.md`）永遠不會被改寫。當 Stop hook 在收尾時擋下舊格式的 Handoff，訊息會叫 agent 自己跑對應的 migrate 指令（Claude plugin 用 `/devlog-tracker:migrate`，Codex 用 `$devlog-migrate`；底層是 `migrate-handoff.sh`）再重新結束這一輪——一般情況不用你動手。migrate 會直接改寫 `devlog.md`、分支 devlog 檔、開著的 Round（`.round-current.md`）與 `handoff.md`／`handoff.<branch>.md`，每個改過的檔旁邊留一份 `*.pre-migrate` 備份；無法精確轉換的輪次保留原樣，列在 `SKIP` 行。如果 agent 一直寫舊格式、沒有照著修，請更新 plugin 或重跑 `npx devlog-tracker init`，再使用對應的 start 指令（Claude plugin 用 `/devlog-tracker:start`，Codex 用 `$devlog-start`）。
 
 ## Hook 會自動做的事
 

package/cli/agents-md.js

@@ -22,6 +22,7 @@ function codexBlock() {
 | 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
 | 歸檔 / compact | \`commands/compact.md\` |
 | 清空重編 / clean（不可復原，先問使用者確認） | \`commands/clean.md\` |
+| 舊格式 Handoff 轉 XML / migrate（Stop hook 擋下舊格式時直接跑） | \`commands/migrate.md\` |
 | 保存主題 / keep、接續具名檔 / resume、跨主題總覽 / overview | \`commands/keep.md\`、\`commands/resume.md\`、\`commands/overview.md\` |
 | 整理所有 devlog（跨分支檔、archive、既有 keep 檔重新分主題） / keep-all | \`commands/keep-all.md\` |
 | 沉澱規範寫進 CLAUDE.md／AGENTS.md / promote | \`commands/promote.md\` |

package/cli/agents-md.test.js

@@ -92,6 +92,16 @@ test('init --codex writes AGENTS.md and project skills; --cursor alone does not'
     assert.match(skill, new RegExp(`^---\\nname: ${name}\\ndescription: ".+"\\n---\\n`));
   }
   assert.ok(!fs.existsSync(path.join(withCodex, '.codex', 'prompts')));
+  const installedHooks = JSON.parse(fs.readFileSync(path.join(withCodex, '.codex', 'hooks.json'), 'utf8'));
+  assert.equal(installedHooks.hooks.Interrupt[0].hooks[0].timeout, 3);
+  assert.equal(
+    installedHooks.hooks.Interrupt[0].hooks[0].command,
+    `bash "${path.join(withCodex, '.devlog-tracker', 'codex', 'hooks', 'on-interrupt.sh')}"`
+  );
+  assert.equal(
+    installedHooks.hooks.SubagentStart[0].hooks[0].command,
+    `bash "${path.join(withCodex, '.devlog-tracker', 'codex', 'hooks', 'on-subagent-start.sh')}"`
+  );
 
   const upgraded = tmp();
   const legacy = path.join(upgraded, '.codex', 'prompts');

package/cli/platforms/claude.js

@@ -21,6 +21,7 @@ function claudeBlock() {
 | 接續上一題 / continue（換過工具或 \`/clear\` 之後） | \`commands/continue.md\` |
 | 歸檔 / compact | \`commands/compact.md\` |
 | 清空重編 / clean（不可復原，先問使用者確認） | \`commands/clean.md\` |
+| 舊格式 Handoff 轉 XML / migrate（Stop hook 擋下舊格式時直接跑） | \`commands/migrate.md\` |
 | 保存主題 / keep、接續具名檔 / resume、跨主題總覽 / overview | \`commands/keep.md\`、\`commands/resume.md\`、\`commands/overview.md\` |
 | 整理所有 devlog（跨分支檔、archive、既有 keep 檔重新分主題） / keep-all | \`commands/keep-all.md\` |
 | 沉澱規範寫進 CLAUDE.md／AGENTS.md / promote | \`commands/promote.md\` |

package/codex/hooks/on-interrupt.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Codex Interrupt: close the active round as interrupted. The event is
+# advisory and has a short timeout, so failures must not affect Codex.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
+[ -d "$PLUGIN_SCRIPTS" ] || exit 0
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export DEVLOG_PROJECT_DIR="$ROOT"
+bash "$PLUGIN_SCRIPTS/close-open-round.sh" "Interrupt:cancelled" >/dev/null 2>&1 || true
+exit 0

package/codex/hooks/on-pre-tool.sh

@@ -10,10 +10,78 @@ _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
 [ -d "$PLUGIN_SCRIPTS" ] || exit 0
+# shellcheck source=../../core/scripts/json-field.sh
+. "$PLUGIN_SCRIPTS/json-field.sh"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
 export DEVLOG_PROJECT_DIR="$ROOT"
+
+codex_access_payload() {
+  printf '{"tool_name":"%s","tool_input":{"file_path":".devlog/.round-current.md"},"session_id":"%s","agent_id":"%s"}' \
+    "$1" "$(json_escape "$(json_str_field "$INPUT" session_id)")" "$(json_escape "$(json_str_field "$INPUT" agent_id)")"
+}
+
+TOOL_NAME="$(json_str_field "$INPUT" tool_name)"
+if [ "$TOOL_NAME" = Bash ] || [ "$TOOL_NAME" = apply_patch ]; then
+  if command -v jq >/dev/null 2>&1; then
+    COMMAND="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+  else
+    COMMAND="$(json_str_field "$INPUT" command)"
+  fi
+fi
+
+# Codex CLI reads files through Bash. Permit a single cat of the current
+# devlog while the core valve is blocking other tools.
+if [ "$TOOL_NAME" = Bash ]; then
+  CWD="$(json_str_field "$INPUT" cwd)"
+  case "$COMMAND" in
+    "cat $ROOT/.devlog/.round-current.md"|"cat \"$ROOT/.devlog/.round-current.md\"")
+      INPUT="$(codex_access_payload Read)"
+      ;;
+    'cat .devlog/.round-current.md'|'cat ".devlog/.round-current.md"')
+      [ "$CWD" != "$ROOT" ] || INPUT="$(codex_access_payload Read)"
+      ;;
+  esac
+fi
+
+# During a blocked segment, the core permits edits to the current devlog.
+# Codex's file editor is apply_patch, whose only file path is inside the patch
+# string. Normalize only patches that exclusively add/update that file.
+if [ "$TOOL_NAME" = apply_patch ]; then
+  CWD="$(json_str_field "$INPUT" cwd)"
+  [ -n "$CWD" ] || CWD="$ROOT"
+  PATCH="$COMMAND"
+  if printf '%s\n' "$PATCH" | awk -v cwd="$CWD" -v root="$ROOT" '
+    function normalize(path, count, parts, stack, depth, i, result) {
+      if (substr(path, 1, 1) != "/") path = cwd "/" path
+      count = split(path, parts, "/")
+      depth = 0
+      for (i = 1; i <= count; i++) {
+        if (parts[i] == "" || parts[i] == ".") continue
+        if (parts[i] == "..") { if (depth > 0) depth--; continue }
+        stack[++depth] = parts[i]
+      }
+      result = ""
+      for (i = 1; i <= depth; i++) result = result "/" stack[i]
+      return result == "" ? "/" : result
+    }
+    NR == 1 && $0 != "*** Begin Patch" { bad = 1 }
+    /^\*\*\* (Add|Update|Delete) File: / {
+      path = $0; sub(/^\*\*\* (Add|Update|Delete) File: /, "", path)
+      if ($0 ~ /^\*\*\* Delete File: / || normalize(path) != normalize(root "/.devlog/.round-current.md")) bad = 1
+      files++
+    }
+    /^\*\*\* Move to: / { bad = 1 }
+    $0 == "*** End Patch" { ended = 1; next }
+    END { exit !(files > 0 && ended && !bad) }
+  '; then
+    INPUT="$(codex_access_payload Write)"
+  fi
+fi
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/segment-watch.sh"
 RC=$?
-[ "$RC" -eq 2 ] && exit 2
+if [ "$RC" -eq 2 ]; then
+  printf 'Codex CLI：先用 cat "%s/.devlog/.round-current.md" 讀取，再用 apply_patch 只修改這份檔案；完成後重試原工具。\n' "$ROOT" >&2
+  exit 2
+fi
 exit 0

package/codex/hooks/on-session-end.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Codex SessionEnd wrapper. on-session-end.sh (shared) reads a "reason"
-# field. Codex's own field for "why the session ended" is documented
-# inconsistently as either "why" or "reason" - try both, default to
+# field. Codex documents `reason` (currently only `other`); accept older
+# `why` payloads too and default to
 # "unknown" rather than guessing further, and rebuild a synthetic payload
 # so the shared script's json_str_field lookup always finds "reason".
 set -uo pipefail
@@ -14,10 +14,10 @@ export DEVLOG_PROJECT_DIR="$ROOT"
 
 REASON=""
 if command -v jq >/dev/null 2>&1; then
-  REASON="$(printf '%s' "$INPUT" | jq -r '.why // .reason // empty' 2>/dev/null || true)"
+  REASON="$(printf '%s' "$INPUT" | jq -r '.reason // .why // empty' 2>/dev/null || true)"
 else
-  REASON="$(printf '%s' "$INPUT" | grep -o '"why"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"why"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
-  [ -n "$REASON" ] || REASON="$(printf '%s' "$INPUT" | grep -o '"reason"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  REASON="$(printf '%s' "$INPUT" | grep -o '"reason"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  [ -n "$REASON" ] || REASON="$(printf '%s' "$INPUT" | grep -o '"why"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"why"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
 fi
 [ -n "$REASON" ] || REASON="unknown"
 

package/codex/hooks/on-session-start.sh

@@ -5,9 +5,8 @@
 # JSON-in shape as Claude Code, so we assume the same is true for stdout-out
 # here and skip any envelope too.
 #
-# One documented field-name gap: Codex's SessionStart payload may call the
-# "how did this session start" field `how` instead of Claude Code's `source`.
-# We try both and default to "startup" on purpose: session-start-devlog.sh
+# Codex's documented SessionStart field is `source`. Accept older `how`
+# payloads too, and default to "startup" on purpose: session-start-devlog.sh
 # SKIPS the dangling-round heal when source is missing/unrecognized (same as
 # `compact`); the wrapper forces SRC="startup" so healing runs.
 set -uo pipefail
@@ -20,10 +19,10 @@ export DEVLOG_PROJECT_DIR="$ROOT"
 
 SRC=""
 if command -v jq >/dev/null 2>&1; then
-  SRC="$(printf '%s' "$INPUT" | jq -r '.how // .source // empty' 2>/dev/null || true)"
+  SRC="$(printf '%s' "$INPUT" | jq -r '.source // .how // empty' 2>/dev/null || true)"
 else
-  SRC="$(printf '%s' "$INPUT" | grep -o '"how"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"how"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
-  [ -n "$SRC" ] || SRC="$(printf '%s' "$INPUT" | grep -o '"source"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"source"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  SRC="$(printf '%s' "$INPUT" | grep -o '"source"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"source"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  [ -n "$SRC" ] || SRC="$(printf '%s' "$INPUT" | grep -o '"how"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"how"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
 fi
 [ -n "$SRC" ] || SRC="startup"
 

package/codex/hooks/on-stop.sh

@@ -8,11 +8,12 @@ set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
 PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
-[ -d "$PLUGIN_SCRIPTS" ] || exit 0
+[ -d "$PLUGIN_SCRIPTS" ] || { printf '{}\n'; exit 0; }
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
 export DEVLOG_PROJECT_DIR="$ROOT"
-printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/enforce-devlog.sh"
+printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/enforce-devlog.sh" >/dev/null
 RC=$?
 [ "$RC" -eq 2 ] && exit 2
+printf '{}\n'
 exit 0

package/codex/hooks/on-subagent-start.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Codex SubagentStart: give the child the shared Lessons Mode guidance.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
+[ -d "$PLUGIN_SCRIPTS" ] || exit 0
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+# A subagent may run in a separate worktree. Installed hook scripts live under
+# <project>/.devlog-tracker/codex/hooks, so their path identifies the parent.
+case "$SCRIPT_DIR" in
+  */.devlog-tracker/codex/hooks)
+    ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+    ;;
+esac
+export DEVLOG_PROJECT_DIR="$ROOT"
+printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/lessons-subagent-start.sh" || true
+exit 0

package/codex/hooks/project-dir.sh

@@ -10,4 +10,19 @@ if command -v jq >/dev/null 2>&1; then
 else
   ROOT="$(printf '%s' "$INPUT" | grep -o '"cwd"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
 fi
-printf '%s\n' "${ROOT:-.}"
+[ -n "$ROOT" ] || ROOT=.
+# Codex can start from a subdirectory while loading the repo's hooks.json.
+# npx uses the vendored marker; a Codex plugin has no project-local vendor
+# directory, so use the nearest tracked project or existing .devlog root.
+SEARCH="$ROOT"
+while [ -d "$SEARCH" ]; do
+  if [ -d "$SEARCH/.devlog-tracker" ] || [ -d "$SEARCH/.devlog" ] || [ -e "$SEARCH/.git" ]; then
+    printf '%s\n' "$SEARCH"
+    exit 0
+  fi
+  PARENT="${SEARCH%/*}"
+  [ -n "$PARENT" ] || PARENT=/
+  [ "$PARENT" != "$SEARCH" ] || break
+  SEARCH="$PARENT"
+done
+printf '%s\n' "$ROOT"