devlog-tracker 0.29.2 → 0.30.0

package/README.md

@@ -2,7 +2,7 @@
 
 *English | [繁體中文](README.zh-TW.md)*
 
-**Version** 0.29.2
+**Version** 0.30.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.
 
@@ -220,7 +220,7 @@ Switching branches within the same working directory automatically splits the ma
 
 #### Lessons Mode (off by default, not automatic)
 
-When enabled, a development-lesson entry is only considered when a `BLOCKED` status resolves, an obvious detour happens, or workspace drift accumulates to a threshold (default 3, adjustable via `/devlog-tracker:lessons-drift <count>`); it's stored per-topic as `devlog.lessons.<topic>.md`, with `devlog.md` keeping only a heading index. None of the three signals are enforced by a hook themselves, and this isn't a knowledge base (architectural decisions still live in `docs/design/*.md`). See [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md).
+When enabled, a development-lesson entry is only considered when a `BLOCKED` status resolves, an obvious detour happens, or workspace drift accumulates to a threshold (default 3, adjustable via `/devlog-tracker:lessons-drift <count>`); it's stored per-topic as `devlog.lessons.<topic>.md`, with `devlog.md` keeping only a heading index. On Claude Code, subagents and Workflow agents get the `lessons-append.sh` usage (with absolute paths, so worktree isolation is safe) injected at `SubagentStart` and may record an entry themselves; when a subagent returns or a background task-notification arrives, the main session sees a `[Lessons Mode 提示]` advisory (`failed`/`killed` also count toward the shared counter). None of these signals enforce writing an entry, and this isn't a knowledge base (architectural decisions still live in `docs/design/*.md`). See [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md).
 
 ## Tests
 

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 *[English](README.md) | 繁體中文*
 
-**版本** 0.29.2
+**版本** 0.30.0
 
 在專案中維護一份 `.devlog/devlog.md`，把每一輪對話的請求、決策與結果寫成永久紀錄。對話一 `/clear` 或換 session 就沒了；這份檔案取代那個缺口，讓工作可以中斷再接。沒下過 `/devlog-tracker:start` 時，裝著也不會動任何檔案。
 
@@ -220,7 +220,7 @@ Claude 用純文字結尾提出問題、下一則訊息才拿到答案時，不
 
 #### Lessons Mode（預設關閉，不自動）
 
-開著時，Status 從 `BLOCKED` 解開、明顯繞路，或工作區漂移累積達門檻（預設 3 次，`/devlog-tracker:lessons-drift <次數>` 可調）才考慮記一筆開發歷程教訓，per-topic 存成 `devlog.lessons.<topic>.md`，`devlog.md` 只留標題索引。三種訊號都完全不 hook 強制寫入本身、不是知識庫（架構決策仍在 `docs/design/*.md`）。細節見 [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md)。
+開著時，Status 從 `BLOCKED` 解開、明顯繞路，或工作區漂移累積達門檻（預設 3 次，`/devlog-tracker:lessons-drift <次數>` 可調）才考慮記一筆開發歷程教訓，per-topic 存成 `devlog.lessons.<topic>.md`，`devlog.md` 只留標題索引。Claude Code 上，sub agent／Workflow agent 開始時（`SubagentStart`）會被注入 `lessons-append.sh` 的用法（絕對路徑，worktree isolation 也不會寫錯地方），可以自己記一筆；sub agent 回來或背景任務通知到達時，主 session 會看到一句 `[Lessons Mode 提示]`（`failed`／`killed` 另算進共用計數器）。這些訊號都完全不 hook 強制寫入本身、不是知識庫（架構決策仍在 `docs/design/*.md`）。細節見 [`docs/design/lessons-mode.md`](docs/design/lessons-mode.md)。
 
 ## 測試
 

package/claude/hooks.json

@@ -31,6 +31,27 @@
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/lessons-subagent-start.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/core/scripts/lessons-subagent-done.sh\""
+          }
+        ]
+      }
+    ],
     "PostToolUseFailure": [
       {
         "hooks": [

package/core/scripts/lessons-subagent-done.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# PostToolUse hook（Claude Code，matcher Agent|Task）：前景 sub agent 跑完、
+# 結果回到主 session 時，Lessons Mode 開著就用 additionalContext 提示主
+# session 檢查 sub agent 訊號（docs/design/lessons-mode.md「sub agent／
+# workflow 情境」）。背景 agent 在這裡只是剛啟動（tool_response.status 為
+# async_launched），完成時改由 round-start.sh 的 task-notification 分支提示，
+# 這裡略過；sub agent 自己再派 agent（payload 帶 agent_id）也略過。
+# fail-open：任何問題都 exit 0、不輸出。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$HOOKS_DIR/json-field.sh"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+[ -f "$PROJECT_DIR/.devlog/.lessons-enabled" ] || exit 0
+
+INPUT="$(cat 2>/dev/null || true)"
+[ -n "$(json_str_field "$INPUT" agent_id)" ] && exit 0
+
+ASYNC=0
+if command -v jq >/dev/null 2>&1; then
+  if printf '%s' "$INPUT" | jq -e '(.tool_response.status? == "async_launched") or (.tool_response.isAsync? == true)' >/dev/null 2>&1; then
+    ASYNC=1
+  fi
+else
+  case "$INPUT" in
+    *'"status":"async_launched"'*|*'"isAsync":true'*) ASYNC=1 ;;
+  esac
+fi
+[ "$ASYNC" -eq 1 ] && exit 0
+
+printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"[Lessons Mode 提示] sub agent 完成。讀完回報後檢查：verify 推翻先前的 fix／claim、sub agent 自陳繞路、多個 agent 卡在類似問題、成果被打回票——有的話可考慮用 lessons-append.sh 記一筆（sub agent 若已自己記過就不用重複），非強制。"}}'
+exit 0

package/core/scripts/lessons-subagent-start.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# SubagentStart hook（Claude Code）：Lessons Mode 開著時，把「可以自己呼叫
+# lessons-append.sh」的說明注入 sub agent／Workflow agent 的 context
+# （docs/design/lessons-mode.md「sub agent／workflow 情境」）。
+# sub agent 的 Bash 裡沒有 CLAUDE_PROJECT_DIR，isolation: "worktree" 時 cwd
+# 還是 worktree（沒有 .devlog/），所以專案目錄跟腳本路徑都在這裡寫死成
+# 主專案的絕對路徑。fail-open：任何問題都 exit 0、不輸出。
+
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+HOOKS_DIR="$(cd "${_src%/*}" && pwd)"
+PROJECT_DIR="${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -f "$PROJECT_DIR/.devlog/.enabled" ] || exit 0
+[ -f "$PROJECT_DIR/.devlog/.lessons-enabled" ] || exit 0
+PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd)" || exit 0
+cat >/dev/null 2>&1 || true
+
+MSG="[devlog-tracker Lessons Mode] 這個專案開著 Lessons Mode：記錄開發**過程**踩過的坑（不是架構知識）。如果這次任務中你繞了一大圈才找到對的做法、先前的 fix／claim 被驗證推翻、或卡在某個值得後人避開的坑，可以直接記一筆（非強制，沒有就不用記）：
+
+DEVLOG_PROJECT_DIR='${PROJECT_DIR}' bash '${HOOKS_DIR}/lessons-append.sh' --topic '<kebab-case 主題，2–4 段>' --text '<一段自由散文：卡在哪、怎麼解開、下次怎麼避免>'
+
+路徑都是絕對路徑，在 worktree 裡也照原樣用，不要改成相對路徑。有記的話，在最終回報裡用一句話說明記了哪個主題；腳本回報 NEW_TOPIC 時可改用它列出的既有主題重跑。"
+
+json_escape() {
+  printf '%s' "$1" | awk '
+    BEGIN { ORS = "" }
+    {
+      gsub(/\\/, "\\\\"); gsub(/"/, "\\\""); gsub(/\t/, "\\t"); gsub(/\r/, "\\r")
+      if (NR > 1) print "\\n"
+      print
+    }'
+}
+
+printf '{"hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"%s"}}\n' "$(json_escape "$MSG")"
+exit 0

package/core/scripts/round-start.sh

@@ -123,6 +123,20 @@ if [ "$TASK_NOTIF" -eq 1 ]; then
   else
     PROMPT="$NOTIF_SUMMARY"
   fi
+
+  # Lessons Mode：背景 sub agent／Workflow 完成時機械提示主 session 檢查
+  # sub agent 訊號（docs/design/lessons-mode.md「sub agent／workflow 情境」）；
+  # failed／killed 另外算進共用計數器。span 開著也照印——長任務正是會派
+  # 背景 agent 的場景。
+  if [ -f "$DEVLOG_DIR/.lessons-enabled" ]; then
+    printf '\n[Lessons Mode 提示] 背景任務完成（status=%s）。讀完回報後檢查：verify 推翻先前的 fix／claim、sub agent 自陳繞路、多個 agent 卡在類似問題、成果被打回票——有的話可考慮用 lessons-append.sh 記一筆（sub agent 若已自己記過就不用重複），非強制。\n' "${NOTIF_STATUS:-unknown}"
+    case "$NOTIF_STATUS" in
+      failed|killed)
+        lessons_advisory_migrate "$DEVLOG_DIR"
+        lessons_advisory_bump "$ADVISORY_FILE"
+        ;;
+    esac
+  fi
 fi
 
 if [ "$SPAN_SKIP" -eq 1 ]; then

package/core/scripts/tests/test-lessons-subagent-hooks.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Self-check for lessons-subagent-start.sh (SubagentStart) and
+# lessons-subagent-done.sh (PostToolUse Agent|Task). Run:
+#   bash core/scripts/tests/test-lessons-subagent-hooks.sh
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+DEVLOG_DIR="$TMP_ROOT/.devlog"
+mkdir -p "$DEVLOG_DIR"
+
+FAIL=0
+assert_contains() {
+  local desc="$1" needle="$2" haystack="$3"
+  case "$haystack" in
+    *"$needle"*) echo "PASS: $desc" ;;
+    *) echo "FAIL: $desc (missing: $needle)"; FAIL=1 ;;
+  esac
+}
+assert_empty() {
+  local desc="$1" out="$2"
+  if [ -z "$out" ]; then echo "PASS: $desc"; else echo "FAIL: $desc (got: $out)"; FAIL=1; fi
+}
+assert_valid_json() {
+  local desc="$1" out="$2"
+  if ! command -v jq >/dev/null 2>&1; then echo "SKIP: $desc (no jq)"; return 0; fi
+  if printf '%s' "$out" | jq -e . >/dev/null 2>&1; then echo "PASS: $desc"; else echo "FAIL: $desc (invalid JSON: $out)"; FAIL=1; fi
+}
+
+START_IN='{"session_id":"s1","cwd":"/elsewhere/.claude/worktrees/agent-x","agent_id":"a1","agent_type":"general-purpose","hook_event_name":"SubagentStart"}'
+SYNC_DONE='{"session_id":"s1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"status":"completed","content":[{"type":"text","text":"done"}]}}'
+ASYNC_DONE='{"session_id":"s1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"isAsync":true,"status":"async_launched","agentId":"a1"}}'
+NESTED_DONE='{"session_id":"s1","agent_id":"a1","hook_event_name":"PostToolUse","tool_name":"Agent","tool_input":{"prompt":"p"},"tool_response":{"status":"completed"}}'
+
+# --- disabled: both hooks silent -------------------------------------------
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_empty "start: .enabled absent -> silent" "$OUT"
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: .enabled absent -> silent" "$OUT"
+
+touch "$DEVLOG_DIR/.enabled"
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_empty "start: lessons off -> silent" "$OUT"
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: lessons off -> silent" "$OUT"
+
+touch "$DEVLOG_DIR/.lessons-enabled"
+
+# --- SubagentStart: inject lessons-append.sh instructions with absolute paths
+OUT="$(printf '%s' "$START_IN" | bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_valid_json "start: output is valid JSON" "$OUT"
+assert_contains "start: hookEventName SubagentStart" '"hookEventName":"SubagentStart"' "$OUT"
+assert_contains "start: additionalContext present" '"additionalContext":' "$OUT"
+assert_contains "start: pins the main project dir, not the agent cwd" "DEVLOG_PROJECT_DIR='$TMP_ROOT'" "$OUT"
+assert_contains "start: absolute lessons-append.sh path" "$SCRIPT_DIR/lessons-append.sh" "$OUT"
+assert_contains "start: asks to mention it in the final report" "最終回報" "$OUT"
+
+# relative CLAUDE_PROJECT_DIR still resolves to an absolute path
+(cd "$TMP_ROOT" && OUT="$(printf '%s' "$START_IN" | CLAUDE_PROJECT_DIR=. bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+ case "$OUT" in *"DEVLOG_PROJECT_DIR='$TMP_ROOT'"*|*"DEVLOG_PROJECT_DIR='$(pwd -P)'"*) echo "PASS: start: relative project dir made absolute" ;;
+   *) echo "FAIL: start: relative project dir not made absolute ($OUT)"; exit 1 ;; esac) || FAIL=1
+
+# path needing JSON escaping stays valid JSON
+QDIR="$TMP_ROOT/we\"ird"
+mkdir -p "$QDIR/.devlog"
+touch "$QDIR/.devlog/.enabled" "$QDIR/.devlog/.lessons-enabled"
+OUT="$(printf '%s' "$START_IN" | CLAUDE_PROJECT_DIR="$QDIR" bash "$SCRIPT_DIR/lessons-subagent-start.sh")"
+assert_valid_json "start: quote in project path still valid JSON" "$OUT"
+
+# --- PostToolUse(Agent): foreground completion only -------------------------
+OUT="$(printf '%s' "$SYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_valid_json "done: output is valid JSON" "$OUT"
+assert_contains "done: hookEventName PostToolUse" '"hookEventName":"PostToolUse"' "$OUT"
+assert_contains "done: sub agent advisory" "[Lessons Mode 提示] sub agent 完成" "$OUT"
+
+OUT="$(printf '%s' "$ASYNC_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: async launch -> silent (task-notification covers it)" "$OUT"
+
+OUT="$(printf '%s' "$NESTED_DONE" | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+assert_empty "done: nested (agent_id set) -> silent" "$OUT"
+
+OUT="$(printf '%s' 'not json' | bash "$SCRIPT_DIR/lessons-subagent-done.sh")"
+RC=$?
+[ "$RC" -eq 0 ] && echo "PASS: done: garbage stdin fails open" || { echo "FAIL: done: garbage stdin exit $RC"; FAIL=1; }
+
+if [ "$FAIL" -eq 0 ]; then
+  echo "All checks passed."
+  exit 0
+else
+  echo "Some checks FAILED."
+  exit 1
+fi

package/core/scripts/tests/test-round-start.sh

@@ -1050,6 +1050,55 @@ assert_not_contains "lessons off: no BLOCKED-accumulation advisory" "[Lessons Mo
 rm -rf "$NOLES_DIR"
 export CLAUDE_PROJECT_DIR="$TMP_ROOT"
 
+# --- lessons: background agent / workflow task-notification advisory ------
+TN_DIR="$(mktemp -d)"
+mkdir -p "$TN_DIR/.devlog"
+touch "$TN_DIR/.devlog/.enabled" "$TN_DIR/.devlog/.lessons-enabled"
+export CLAUDE_PROJECT_DIR="$TN_DIR"
+tn_notif() {
+  printf '{"prompt":"<task-notification><task-id>t9</task-id><status>%s</status><summary>Agent \\"x\\" finished</summary></task-notification>"}' "$1"
+}
+tn_reset() {
+  rm -f "$TN_DIR/.devlog/.round-open" "$TN_DIR/.devlog/.round-current.md"
+  printf '## Round 1 — 2026-09-23T00:00:00+0800\n\n### User Input\n```text\nx\n```\n\n### Summary\ns\n\n### Status\nDONE\n' > "$TN_DIR/.devlog/devlog.md"
+}
+
+tn_reset
+printf '%s\n' '{"count": 0, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif completed: sub agent advisory printed" "[Lessons Mode 提示] 背景任務完成（status=completed）" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif completed does not bump counter" || { echo "FAIL: completed bumped counter"; FAIL=1; }
+
+tn_reset
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif failed: advisory printed" "背景任務完成（status=failed）" "$OUT"
+grep -q '"count": 1' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif failed bumps counter" || { echo "FAIL: failed did not bump counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif killed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif killed at threshold: shared nudge printed" "流程訊號已累積出現 3 次" "$OUT"
+grep -q '"count": 0' "$TN_DIR/.devlog/.lessons-advisory-state" && echo "PASS: task-notif killed resets counter at threshold" || { echo "FAIL: killed did not reset counter"; FAIL=1; }
+
+tn_reset
+printf '%s\n' '{"round": 1, "ticks_since_checkin": 0, "max_silent_ticks": 5}' > "$TN_DIR/.devlog/.span-open"
+OUT="$(tn_notif completed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_contains "task-notif during span: advisory still printed" "背景任務完成（status=completed）" "$OUT"
+rm -f "$TN_DIR/.devlog/.span-open"
+
+tn_reset
+rm -f "$TN_DIR/.devlog/.lessons-enabled" "$TN_DIR/.devlog/.lessons-advisory-state"
+OUT="$(tn_notif failed | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "task-notif with lessons off: no advisory" "[Lessons Mode 提示]" "$OUT"
+[ ! -f "$TN_DIR/.devlog/.lessons-advisory-state" ] && echo "PASS: task-notif with lessons off leaves no advisory-state" || { echo "FAIL: advisory-state created while lessons off"; FAIL=1; }
+
+touch "$TN_DIR/.devlog/.lessons-enabled"
+tn_reset
+OUT="$(printf '%s' '{"prompt":"plain message"}' | bash "$SCRIPT_DIR/round-start.sh" 2>/dev/null)"
+assert_not_contains "plain prompt: no background-task advisory" "背景任務完成" "$OUT"
+rm -rf "$TN_DIR"
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+
 if [ "$FAIL" -eq 0 ]; then
   echo "All checks passed."
   exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlog-tracker",
-  "version": "0.29.2",
+  "version": "0.30.0",
   "description": "npx installer for devlog-tracker's Claude Code, Cursor and Codex adapters.",
   "bin": {
     "devlog-tracker": "bin/devlog-tracker.js"

package/skills/devlog-tracker/SKILL.md

@@ -467,8 +467,10 @@ Handoff。核對用 `commands/continue.md` 步驟 5.1–5.2（不要跟著做 5.
 若這輪任務是透過 Agent 工具派 sub agent，或用 Workflow 工具跑多階段 pipeline，一樣可能
 踩到值得記的坑，只是沒有 Round／Status 可比對訊號；讀完 sub agent／workflow 的最終回報後
 自我判斷（例如 verify 推翻了它先前的 fix、它自陳繞了一圈、多個 agent 重複卡在同一種問題、
-或成果被打回票要求重做），值得的話一樣呼叫 `lessons-append.sh`——sub agent／workflow 本身
-不會、也不需要知道這個機制存在。
+或成果被打回票要求重做），值得的話一樣呼叫 `lessons-append.sh`。Claude Code 上 hook 會自動
+觸發：sub agent／Workflow agent 開始時被注入 `lessons-append.sh` 的絕對路徑用法、可以自己記；
+它回來或背景任務通知到達時，你會看到一句 `[Lessons Mode 提示]`（`failed`／`killed` 另算進
+共用計數器）。sub agent 已記過的不用重複記。
 
 寫法、per-topic 存檔規則、索引重建、機制性訊號細節，見
 `${CLAUDE_PLUGIN_ROOT}/skills/devlog-tracker/references/lessons-mode.md`（完整

package/skills/devlog-tracker/references/lessons-mode.md

@@ -49,8 +49,14 @@ verify 階段推翻了 sub agent 先前的 fix／claim、sub agent 自陳繞了
 裡多個 agent 各自卡在類似問題（彙整成一筆更有代表性的）、sub agent 的成果被使用者或
 reviewer 打回票要求重做。
 
-sub agent 不需要知道 Lessons Mode 存在；不新增回報格式，你覺得這次任務可能踩雷時，自己
-決定要不要在 dispatch prompt 裡順口提一句「回報時順便說一下有沒有繞路」。永遠是你（主
-session）讀完回報後自己判斷主題、呼叫 `lessons-append.sh`——sub agent／workflow 本身不
-直接呼叫，避免 worktree isolation 下環境變數指錯專案目錄。詳見
+Claude Code 上 hook 會自動觸發（只在 Lessons Mode 開著時）：
+- sub agent／Workflow agent 開始時（`SubagentStart`），hook 會把 `lessons-append.sh` 的用法
+  連同**主專案絕對路徑**注入它的 context，它覺得值得就自己記一筆，並在最終回報裡說一聲。
+  worktree isolation 下也照那條絕對路徑指令跑，不會寫錯地方。
+- 前景 sub agent 回來時（`PostToolUse`），或背景 sub agent／Workflow 的 task-notification
+  到達時（`round-start.sh`），你會看到一句 `[Lessons Mode 提示]`，提醒你檢查上面四種訊號；
+  背景任務 `status` 是 `failed`／`killed` 時還會算進共用計數器。
+
+看到提示後：sub agent 已說明記過的主題不要重複記；多個 agent 卡在同一種問題時，由你彙整成
+一筆更有代表性的。一樣全部非強制。Codex／Cursor 沒有對應 hook，仍是你自己判斷。詳見
 `docs/design/lessons-mode.md`「sub agent／workflow 情境的自我判斷訊號」。