Claude Code Hooks × Sub-Agent × /plugins 深度研究（2026-05-02）

🔗 承接：knowledge/analyses/2026-04-27-threads-inspiri-flow-agent-hooks.md（概念層） 本文補入：技術規格 + tzlth-hq 現況對照 + P3暫緩條件重評 研究工具：claude-code-guide agent（官方文件直接查詢） 研究日期：2026-05-02

---

背景與目的

2026-04-27 已完成 Agent 5層架構的概念層分析，結論：

• 前 3 層（CLAUDE.md + SKILL + Hooks）已完整覆蓋 ✅
• 後 2 層（Sub-agent + Plugin/外掛）P3暫緩，重啟條件已定義

本次深入到技術規格層，目標：

1. Hooks：確認完整事件類型（現有知識只列了 7 種，實際更多）
2. Sub-Agent：理解技術限制與應用邊界
3. /plugins：釐清這個概念在 Claude Code 中的確切定義

---

Part 1：Hooks 完整技術規格

1-1 事件類型完整清單（共 25+ 種）

⚠️ 重要發現：claude-code-structure-guide.md（2026-03-30 記錄）只列了 8 種，實際目前有 25+ 種。

---

1-2 關鍵事件 JSON 規格

PreToolUse（最重要 — 可攔截/修改）

// Input (stdin)
{
  "session_id": "abc123",
  "cwd": "/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

// Output (stdout) — 阻止
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "理由回傳給 Claude"
  }
}

// Output — 修改 input
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "npm test --coverage" }
  }
}

permissionDecision 值：

• "allow" → 跳過互動權限提示
• "deny" → 取消工具呼叫，原因回傳 Claude
• "ask" → 顯示正常權限提示
• "defer" → 非互動模式保留待處理

PostToolUse（唯讀 — 可注入上下文）

// Input
{
  "hook_event_name": "PostToolUse",
  "tool_name": "Edit",
  "tool_input": { "file_path": "..." },
  "tool_output": { "result": "..." }
}
// Output — 只能注入上下文
{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "注入給 Claude 的補充說明"
  }
}

❌ PostToolUse 無法阻止或修改輸出。工具已執行。

Stop（完成後品質控制）

// Input
{
  "hook_event_name": "Stop",
  "stop_hook_active": false  // true = 已觸發過，防無限迴圈
}
// Output — 可阻止 Claude 停止
{ "decision": "block", "reason": "收尾七件事尚未完成" }
{ "decision": "allow" }

⚠️ 必須檢查 stop_hook_active！若為 true 時仍返回 "block" = 無限迴圈。

UserPromptSubmit（提示前注入上下文）

// Input
{
  "hook_event_name": "UserPromptSubmit",
  "prompt": "使用者輸入的文字"
}
// Output — 注入上下文（exit 0 + stdout = 直接注入）
// 直接 echo 文字即可，不需 JSON

PostCompact（壓縮後注入提醒）

// Input
{
  "hook_event_name": "PostCompact",
  "source": "manual|auto"
}
// Output — 注入重要提醒
{
  "hookSpecificOutput": {
    "hookEventName": "PostCompact",
    "additionalContext": "壓縮後需執行的重要提醒"
  }
}

---

1-3 Exit Code 完整規範

❌ 不可混用：不能同時 exit 2 又輸出 JSON。兩者選其一。

---

1-4 settings.json 完整格式

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/my-hook.py",
            "timeout": 30,
            "statusMessage": "檢查中..."
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '今日：$(date +%Y-%m-%d)'"
          }
        ]
      }
    ]
  }
}

Hook type 選項：

---

1-5 tzlth-hq 現有 Hooks 狀態 vs 升規機會

現有（已實作）：

高價值升規機會（建議 P2）：

建議立即實作（A）的理由： PostCompact 是被動壓縮最痛的痛點——壓縮後 Claude 重新開始，容易忘記執行 Step 0（清除旗標）。PostCompact Hook 可以在壓縮完成後自動注入一段文字到新的 context，讓 Claude 看到即執行。這是目前人工依賴規則記憶的唯一補強方式。

---

Part 2：Sub-Agent 完整技術規格

2-1 .claude/agents/ 定義格式

---
name: code-reviewer
description: Expert code reviewer. Analyzes code quality, security, and best practices.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: default
maxTurns: 20
background: true
isolation: worktree
---

You are a senior code reviewer...

完整 frontmatter 欄位：

---

2-2 Context 隔離規則（重要）

---

2-3 Token 費用計算

• Sub-agent 的 token（prompt + completion）另外計費，不計入父 session token
• Prompt cache 可跨 fork 共享
• 無官方記載的 sub-agent 數量上限（可多個平行執行）

---

2-4 P3暫緩條件重評（2026-05-02）

來源：2026-04-27 分析中設定的重啟條件

結論：P3暫緩決策維持不變（3 條件中 1 條達成，需至少 2 條）

技術層面已成熟，但業務規模條件未達。建議：下次重評時間 → 人員擴張時 or 任務量達標時。

---

Part 3：/plugins 定性

3-1 /plugin 指令（是什麼）

Claude Code CLI 有 /plugin（單數）指令，功能：

/plugin install <plugin-name>   # 從市場安裝
/plugin uninstall <plugin-name> # 移除
/plugin list                    # 列出已安裝
/plugin update                  # 更新所有
/plugin enable / disable        # 管理狀態

⚠️ 命名澄清：指令為 /plugin（單數），非 /plugins（複數）。Tim 說的「/plugins 探索」可能指「plugin 系統的探索」，而非一個具體指令。

---

3-2 Plugin 架構

Plugin = 目錄結構，包含：

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # 必需：清單（name/version/description）
├── skills/                 # Skill 定義
├── agents/                 # Agent 定義
├── hooks/
│   └── hooks.json          # Hook 配置
├── .mcp.json               # MCP 伺服器
├── bin/                    # 執行檔（加入 PATH）
└── settings.json           # 預設設定

用途：封裝 skills + agents + hooks + MCP 為一個可分佈的套件。

---

3-3 Skills（新格式）vs Commands（舊格式）

tzlth-hq 現況： 我們用 .claude/skills/ 目錄 ✅ 已是正確的新格式

---

3-4 Plugin 對 tzlth-hq 的意義

tzlth-hq 是個人工作室單人專案，Plugin 的主要價值是「分佈給團隊/社群」。

結論：Plugin 系統對 tzlth-hq 目前無直接應用需求。維持現有 SKILL 架構即可。

📌 深度研究後記（2026-05-10）：本 Part 3 為定性框架（無 marketplace 清單）。2026-05-10 進行了完整官方 Marketplace 探索，含 Glob 本機掃描現有安裝確認（ak-threads-booster v1.1.0）+ WebSearch 官方目錄調查（27 個 Plugin，含 LSP 語言服務 / 整合 / 開發工作流 / 輸出風格）+ 三標準評估。評估結論：typescript-lsp 有潛力（Next.js 開發，零外部依賴），其餘無立即需求。完整報告見 analyses/2026-05-10-claude-code-plugins-official-marketplace.md。

---

維度 9：採用評估（2026-05-02）

✅ 立即採用建議（P2）

採用點 A：PostCompact Hook 自動注入接續提醒

• 觸發事件：PostCompact
• 做什麼：每次壓縮完成後，自動注入一段文字：「⚠️ 壓縮後接續規則已觸發：Step 0 清除 _pending.flag → Step 1 讀取 dev/tasks.md → Step 2 輸出壓縮後查照格式」
• 實作：在 scripts/postcompact-reminder-hook.py 中 echo 這段文字到 stdout，設定於 settings.local.json PostCompact 事件
• 解決問題：IMP-089 壓縮後旗標殘留 + 接續規則忘記執行（出現次數 3+）
• 難度：低（約 15 行 Python）
• 注意事項：此 hook 在 PostCompact 只能注入文字，不能阻止（無 block 機制）

🔍 觀察期（P3）

觀察點 B：Stop Hook 收尾七件事品質控制

• 概念：用 type: "prompt" 的 Stop Hook 讓 Claude 自我評估是否完成收尾七件事
• 風險：需精確處理 stop_hook_active，否則無限迴圈
• 評估：風險高於收益（現有 HARD STOP 已能達到類似效果）→ 待觀察
• 重評時機：收尾七件事遺漏率 > 2次/月時

觀察點 C：SubagentStart/Stop Hook 監控

• 概念：追蹤 sub-agent 的啟動和結束，記錄使用量
• 評估：目前 sub-agent 使用頻率低，監控價值不高 → P3

❌ 不採用

Plugin 系統：個人使用無分佈需求，現有 .claude/skills/ 架構已足夠。

Sub-Agent 擴張：P3暫緩條件 2/3 未達成（人員、任務量），維持現有暫緩決策。

---

關鍵發現摘要

1. Hooks 遠比我們知道的豐富：25+ 種事件（vs 現有知識 8 種）。最有價值但尚未使用的：PostCompact、UserPromptExpansion、SubagentStart/Stop
2. Sub-agent 不能遞迴：sub-agent 內不能再 spawn sub-agent，限制了複雜協作場景
3. PostCompact Hook = 壓縮接續問題的技術解：自動注入提醒，比靠規則記憶更可靠
4. /plugins = plugin 系統 + /plugin CLI 指令，對 tzlth-hq 無即時應用需求
5. 我們的 SKILL 格式（.claude/skills/）已是正確的新格式，無需改變
6. claude-code-structure-guide.md 需要更新：現有 Hooks 章節只列 8 種，實際 25+

---

---

Part 4：Stop Hook 擴充方案設計（Session 95 深度研究）

研究日期：2026-05-02 ｜ 來源：Session 95 claude-code-guide agent 深度查詢 背景：現有 Stop Hook 為 auto-commit bash script。Tim 希望評估兩個升規方向： ① Windows 桌面通知（長任務完成提醒）② 收尾七件事「硬性觸發」

---

4-1 三個關鍵技術問題的研究結果

Q1：Stop Hook stdout 是否注入 Claude context？

結論：❌ 不注入（與 PostCompact 不同）

⚠️ 代理研究差異：claude-code-guide agent 的 Q1 表格誤將 PostCompact 標為 ❌（無注入）。但 tzlth-hq 的 postcompact-reminder-hook.py 已實際驗證 PostCompact exit 0 + stdout text 有效注入 Claude context（Session 94 Tim 確認）。以實測為準，agent 查詢有誤。

Stop Hook 確認：Stop Hook stdout → debug log only，不進入 Claude context。若要影響 Claude 行為，只能透過 decision: block JSON 輸出。

設計影響：無法用 Stop Hook 的 stdout text 在 Claude 的 active context 注入「收尾七件事提醒」。

---

Q2：多 entry Stop Hook 執行順序 + stop_hook_active 作用域

結論 A：所有 entries 並行執行（不是串行）

settings.json Stop Hook 多 entry：

"Stop": [
  { "hooks": [{ entry1: git commit + push }] },   ──┐ 並行執行
  { "hooks": [{ entry2: decision logic    }] }    ──┘
]

→ 如果 entry2 返回 { "decision": "block" }：
  entry1 的 git commit 已在同時執行，block 只能阻止 Claude 停止，不能取消 entry1

結論 B：stop_hook_active 是「block-retry 週期」級別，不是 session 全局鎖

⚠️ 修正原始設計假設：Session 95 查照前假設「stop_hook_active = session 全局鎖，block 每 session 只能觸發一次」為錯誤。正確行為：每次新的獨立 Stop 事件都從 false 開始，stop_hook_active = true 只在「本次被 block 的重試流程」中有效。decision: block 在同一 session 可多次觸發（只要每次都是新的獨立 Stop 事件）。

設計影響：decision: block 技術上可用於多輪攔截，但並行執行造成的雙 auto-commit 問題仍存在。

---

Q3：Windows 桌面通知（無管理員、無額外安裝）

推薦方案：PowerShell Windows.UI.Notifications API（原生，Windows 10+）

# 從 Git Bash 調用（Stop Hook script 片段）
powershell.exe -NonInteractive -Command "
[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > \$null
\$tmpl = '<toast><visual><binding template=\"ToastText02\"><text id=\"1\">職涯停看聽 HQ</text><text id=\"2\">Claude 完成回應，請確認收尾七件事</text></binding></visual></toast>'
\$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
\$xml.LoadXml(\$tmpl)
\$toast = New-Object Windows.UI.Notifications.ToastNotification \$xml
[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show(\$toast)
" 2>/dev/null || true

---

4-2 設計方案選擇矩陣

---

4-3 推薦方案：A（通知 only）+ 維持現有 auto-commit

理由：

1. 收尾七件事無法真正「硬性強制」：Stop Hook 的 decision: block 只能中斷一次，Claude 可以選擇無視 reason 繼續停止（沒有真正的強制機制）。CLAUDE.md 的規則約束 + Tim 的攔截機制已是可達到的最佳軟性強制。
2. Windows 通知有合理價值：長任務（30+ 分鐘）完成時，桌面通知讓 Tim 不必持續盯著螢幕。
3. 最小修改風險：在現有 Stop Hook entries 旁新增一個通知 entry，不改動 auto-commit 邏輯。

實作建議（設計草稿）：

// settings.local.json 修改
"Stop": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "cd \"C:/Users/USER/Desktop/tzlth-hq\" && git add -A && git diff --cached --quiet || (git commit -m \"自動同步：$(date '+%Y-%m-%d %H:%M')\" && git push origin main) 2>/dev/null || true",
        "timeout": 30
      }
    ]
  },
  {
    "hooks": [
      {
        "type": "command",
        "command": "python -X utf8 C:/Users/USER/Desktop/tzlth-hq/scripts/stop-notification-hook.py",
        "timeout": 10
      }
    ]
  }
]

scripts/stop-notification-hook.py 草稿：

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Stop Hook：Claude 完成回應時發送 Windows 桌面通知
- 目的：長任務完成時提醒 Tim，不需持續盯螢幕
- 注意：每次 Claude 停止都會觸發（包含中間 turn）
"""
import subprocess
import json
import sys

input_data = json.loads(sys.stdin.read())
# 如果是 block 重試中，不發通知（避免重複）
if input_data.get("stop_hook_active", False):
    sys.exit(0)

ps_command = """
try {
    [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
    $tmpl = '<toast><visual><binding template="ToastText02"><text id="1">職涯停看聽 HQ</text><text id="2">Claude 完成回應</text></binding></visual></toast>'
    $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
    $xml.LoadXml($tmpl)
    $toast = New-Object Windows.UI.Notifications.ToastNotification $xml
    [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Claude Code').Show($toast)
} catch {}
"""

subprocess.run(
    ["powershell.exe", "-NonInteractive", "-Command", ps_command],
    capture_output=True, timeout=8
)
sys.exit(0)

⚠️ 每次 turn 都通知的潛在問題：如果對話頻繁，通知可能過多。解法：在腳本中加入「最小間隔 30 秒」的時間戳判斷（存入 scripts/.last-notification），或僅在 Tim 設定特定工作階段時觸發。建議先無條件通知試用 1 週，根據體驗調整。

---

4-4 誠實評估：可達 vs 不可達目標

最終定位：Stop Hook 的正確用途是「完成後輔助動作」（auto-commit、通知），不是「行為強制」。行為強制的正確機制是 CLAUDE.md 規則 + Tim 的攔截指令。

---

Part 5：Sub-Agent 缺口補完 + C-level 平行架構評估（Session 100）

研究日期：2026-05-03 ｜ 來源：Session 100 claude-code-guide agent + CEO 架構分析 背景：Session 93 研究了 Sub-agent 技術規格與 P3暫緩條件。本 Part 補完 3 個技術缺口，並評估是否為 tzlth-hq 設計 C-level 平行架構（CPO/COO/CTO）。

---

5-1 技術缺口補完（Session 93 遺漏）

缺口一：/agents 互動式 CLI vs .claude/agents/ 檔案，有何差異？

結論：兩者是「同一目的地、不同入口」

tzlth-hq 適用：手動編輯 .claude/agents/ 更符合現有工作流（git 管理、可審閱、可 Grep 搜尋）。若未來需要快速建立試驗性 agent，可用 /agents UI。

---

缺口二：Windows 相容性

---

缺口三：@agentname 語法

結論：@agentname 是「指定代理」機制，適用於所有來源的 agent

設計注意：@agentname 的本質是「user-level routing override」——跳過 Claude 的自主委派判斷，直接指定執行者。適合已知特定 agent 能力的場景。

---

5-2 C-level 平行架構設計草稿

本節為設計評估，非採用決策。採用前需 Tim 確認 + 觸發 RCF（條件 3：組織架構異動）。

設計原則

三層 C-level 部門分組

HR 在 tzlth-hq 是「系統員工冊」而非人事部，因此歸 CTO 管（技術基礎建設）。

Frontmatter 範例（CPO）

---
name: cpo-agent
description: Chief Product Officer for 職涯停看聽. Coordinates CNT (content), SOC (community), PRD (product), EDU (courses), GRW (growth analytics). When given a task involving content strategy, product roadmap, or community growth, synthesize inputs from relevant departments and return integrated recommendations. Does NOT directly execute — routes to department-level agents.
tools: Read, Glob, Grep, Agent
disallowedTools: Write, Edit, Bash
model: sonnet
permissionMode: default
maxTurns: 15
background: false
---

# CPO 代理（Chief Product Officer）

## 職責
接收 CEO 的跨部門協調請求，整合 CNT / SOC / PRD / EDU / GRW 五個部門的輸入，輸出統一的行動方向建議。

## 禁止
- 不直接執行任務（Write/Edit 禁用）
- 不跨越 CTO / COO 管轄範圍
- 不決策公司方向（CEO 職責）

---

5-3 P3 重啟條件框架修訂

舊框架的問題

原始條件（2026-04-27 設定）：

「3 條件需達 2 條」的問題：可行性條件（Condition 3）和需求條件（Conditions 1-2）被混合計算。但可行性條件是先決門檻（gate），不是替代需求條件的理由。即使「機制已成熟」，在需求不存在的情況下採用，仍是過早優化。

修訂框架

GATE（先決條件，必須通過才進入評估）：
  ✅ Claude Code sub-agent 機制成熟（已於 2026-05-02 達成）

NEED（需求條件，以下三項任一成立即可重啟）：
  N1: 人員擴張 — Tim 有穩定合作夥伴/助理，需要不同知識背景的上下文切換
  N2: 任務密度持續 — 每日並行任務 > 15 個，持續 4 週以上（非單日爆發）
  N3: CEO 協調瓶頸可觀察 — Tim 或 Claude 自主識別出「多個部門間的跨域決策，因 CEO 同時處理過多而反覆延誤」的具體模式

BENEFIT CHECK（評估時同步確認）：
  Q1: C-level 架構是否能降低 CEO 的認知負荷？還是只是增加路由層？
  Q2: 單人工作室的順序任務模式，是否真的需要平行協調層？
  Q3: 每次 C-level 呼叫的 token 成本（獨立計費）vs 直接部門路由的節省？

當前狀態（2026-05-03）

結論：維持 P3 暫緩（⏸） 下次重評觸發：N1/N2/N3 任一達成，或 Tim 主動提出「感覺 CEO 協調有瓶頸」

---

5-4 採用評估結論

若 Tim 決定採用 C-level 架構：

1. 觸發 RCF（條件 3：組織架構新增 C-level 層）
2. 建立 .claude/agents/cpo-agent.md / coo-agent.md / cto-agent.md（可從本節 frontmatter 範例起草）
3. 更新主 CLAUDE.md 部門架構表（新增 C-level 層）
4. 更新 strategy/department-charters.md（新增 C-level 職責邊界）

---

研究完整性：Part 5 補完 Part 2（Session 93）的 3 個技術缺口，並完成 C-level 設計草稿 + 決策框架修訂。

---

Part 4 研究完成日期：2026-05-02 ｜ 研究方法：Session 95 claude-code-guide agent Q1/Q2/Q3 深度查詢 + 設計方案合成