Kiro 2.13 實戰：Global Hooks 設定一次全 workspace 生效，Introspect Subagent 教你寫 hook

瀏覽次數: 6

你有沒有這種經驗：在 A 專案辛苦調好了一組 hook——存檔自動 lint、commit 前跑安全掃描、危險指令要人工核准——換到 B 專案，全部得重來一遍。改一條規則，要開好幾個 repo 一個一個同步；新 clone 下來的專案還常常忘了把 hook 帶上，防護就這樣破了個洞。

Kiro CLI 2.13.0（AWS 的 Kiro，2026 年 7 月 17 日釋出）針對的正是這件事。這一版在 CLI 3.0 早期存取（kiro-cli --v3）裡塞了兩個東西：Global Hooks（跨 workspace 的全域 hook），以及 Introspect Subagent（一個專門教你怎麼用 Kiro 的內建 subagent）。前者讓你「設一次、全機生效」，後者讓你在還不熟語法時，直接在 CLI 裡問它怎麼寫。

這篇就手把手拆給你看：hook 到底掛在 agent 回合的哪幾個時機、全域怎麼放、每個事件能做什麼、什麼時候該用全域什麼時候該留在專案，以及 Introspect 這個 subagent 實際怎麼用。

本文大綱

先搞懂：Kiro 的 hook 是什麼、掛在哪

Kiro 的 hook 不是 git hook，也不是 IDE 的存檔事件——它是掛在 agent 對話回合裡的鉤子。每當 agent 走到某個時機，Kiro 就會把一段 JSON 從 STDIN 餵給你的 hook 程式，你的程式讀進來、做事、再用 exit code 跟 STDOUT／STDERR 回話。

從官方文件看，每個 hook 收到的 JSON 一定帶三個核心欄位：

{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789"
}

跟工具有關的事件會再多帶 tool_name、tool_input；PostToolUse 還會多一個 tool_response。也就是說，你的 hook 腳本本質上就是一支「讀 STDIN 的 JSON、視情況做事」的小程式——bash、Python、Node 都行，只要能讀標準輸入就好。

Kiro CLI 目前支援 五種觸發事件，按一個回合的時間順序排開：

AgentSpawn — agent 啟動時觸發，沒有工具脈絡。適合開場注入環境資訊或團隊規範。文件特別註明：這個事件永遠不快取。
UserPromptSubmit — 使用者送出提問時觸發，它的輸出會被加進對話脈絡。適合把即時資訊（例如當前 branch、待辦、環境變數）塞給模型。
PreToolUse — 工具執行前觸發，可以驗證並攔截工具呼叫。這是唯一能「擋下動作」的事件。
PostToolUse — 工具執行後觸發，拿得到 tool_response。適合在 agent 寫完檔後自動跑 lint、格式化、型別檢查。
Stop — 助理回應完成、每個 turn 收尾時觸發。

核心機制：exit code 決定 hook 怎麼影響 agent

這是最容易被略過、卻最關鍵的一段。你的 hook 「說了算不算」，看的是 exit code：

exit 0：成功。STDOUT 會被擷取進脈絡，等於你能把訊息喂回給模型。
exit 2：只在 PreToolUse 有效——它會擋下這次工具執行，並把 STDERR 的內容回傳給 LLM。這就是「危險指令攔截」「commit 前必須通過檢查」這類審批閘門的實作方式。
其他 exit code：顯示失敗警告，但動作照樣進行。也就是說，除了 PreToolUse 的 exit 2，其他情況 hook 都擋不住 agent，只能「提供資訊」或「事後補救」。

搭配的還有兩個實用旋鈕：預設 timeout 30 秒（用 timeout_ms 調整），以及 cache_ttl_seconds 控制快取（設 0 關閉；前面提過 AgentSpawn 永不快取）。如果你的 hook 要跑比較久的檢查，記得把 timeout 拉高，不然會被砍掉當成失敗。

還有一個 matcher 欄位，用來指定「這個 hook 要盯哪些工具」。支援的寫法包括：

正規名稱：fs_write、execute_bash、use_aws
別名：write、shell、aws
MCP 格式：@git、@git/status
萬用字元：*（所有工具）或 @builtin（只限內建工具）

舉例：想在「agent 每次執行 shell 指令前」都攔一下審查，matcher 就設 execute_bash（或別名 shell）配 PreToolUse；想在「agent 每次寫檔後」跑 lint，就用 fs_write 配 PostToolUse。

2.13 的主角：Global Hooks——放一次，全 workspace 生效

前面那套機制在 2.13 之前就有了，但有個惱人的限制：hook 是綁專案的。跨專案共用的行為，只能一個一個複製。

2.13 補上的就是這一刀。官方原話是：把 hook 放進 ~/.kiro/hooks/ 這個目錄，它就會在每個 workspace 自動觸發，不必再逐專案重複。文件點名的三個典型場景是：存檔時 lint、commit 前安全檢查、自訂審批閘門——這些「跨專案共用」的行為，正是全域 hook 的甜蜜點。

關鍵是相容性：專案級的 hook 照常運作，跟全域 hook 並存、不衝突。所以你可以把「全公司都要遵守的紅線」放全域，把「這個 repo 特有的規矩」留在專案，兩層疊加。

心智模型很簡單，就是兩個來源、一個回合：

~/.kiro/hooks/     →  全域，跨所有 workspace（2.13 新增）
.kiro/hooks/       →  專案，只在該 repo 生效
        ↓ 兩者同時載入
   同一個 agent 回合，依事件各自觸發

一個可以照做的起手式：把「commit 前安全掃描」升級成全域。做法是準備一支讀 STDIN、針對 execute_bash 的 PreToolUse hook，偵測到 git commit 就跑你的祕密掃描／依賴檢查；沒過就 exit 2 擋下、把原因寫進 STDERR 回給模型。以前這支腳本要在每個 repo 各放一份，現在放進 ~/.kiro/hooks/，新 clone 的專案一進去就自動有防護，不會再漏。

誠實標註：官方 2.13 changelog 與 hooks 文件講清楚了全域 hook 的目錄（~/.kiro/hooks/）、五種事件、STDIN 欄位、exit code 與 matcher 語法；但「單一 standalone hook 檔案的完整 JSON schema」（欄位怎麼命名、matcher／command／timeout_ms 怎麼組在一個檔裡）在公開頁面沒有逐欄列全。CLI 3.0 本來就把 hook 改成「standalone 檔案格式」，所以最保險的做法是——用下面要講的 Introspect subagent，直接在 CLI 裡叫它幫你生一份範本，或跑 kiro-cli --v3 後查內建說明。

另一個主角：Introspect Subagent——不會寫就在 CLI 裡問

第二個新東西，是 Kiro 內建的一個 subagent，叫 Introspect。定位很直白：一個「教你用 Kiro」的 subagent。

它能做三件事：解說 Kiro 的功能、手把手帶你寫 custom agent／hook／steering 檔、以及依你的工作流建議正確的設定。啟用方式跟其他 3.0 功能一樣，跑 kiro-cli --v3 進早期存取。

為什麼這個搭配 Global Hooks 一起出，特別有意思？因為 hook 的語法（五種事件、exit code 的細微差別、matcher 的四種寫法）就是那種「概念不難、但每次都得翻文件確認欄位」的東西。與其自己記，不如在 CLI 裡直接問：「幫我寫一個 PreToolUse hook，攔截所有 git commit、跑安全掃描、沒過就擋下」——讓 Introspect 把範本生出來，你再改。這是很典型的「用 agent 教你用 agent」。

值得補一句：introspect 同時也是 Kiro subagent 可用的內建工具之一（跟 read、write、shell、web_search、web_fetch、knowledge、thinking、todo 等並列）。所以它不只是一個對話入口，而是能被別的 agent 當工具呼叫的能力。

順帶一提：Kiro 的 subagent 怎麼組

既然講到 subagent，順手把 Kiro 的 subagent 機制也交代一下，因為它跟 hook 常一起用來搭工作流。

Kiro 的 subagent 權限，設在 agent 設定檔的 toolsSettings.subagent 底下。官方範例長這樣：

{
  "name": "orchestrator",
  "description": "Agent that coordinates multiple specialized subagents",
  "tools": ["fs_read", "subagent"],
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  }
}

幾個重點：

想讓一個 agent 能派工給別人，它的 tools 陣列裡必須包含 subagent。
availableAgents 限制「這個主 agent 能派給誰」，支援 glob（例如 docs-* 涵蓋所有文件相關 subagent）。
trustedAgents 列的是「可以不用每次跳權限確認」的 subagent。
呼叫方式就是用自然語言點名：> Use the backend agent to refactor the payment module。被叫到的 subagent 會繼承它自己設定檔裡的工具權限、toolsSettings 與 allowedTools。

subagent 的價值在於：把多步驟任務拆成平行、獨立脈絡的子任務，避免把主對話的 context window 撐爆——獨立研究、平行審查、委派給不同設定的 agent，都是它的場景。

什麼時候該用全域、什麼時候別

全域 hook 很香，但不是每條規則都該往 ~/.kiro/hooks/ 塞。給幾個判斷準則：

適合放全域：

跨專案不變的紅線——祕密掃描、危險指令攔截、commit 前檢查。這類規則你希望「每個專案都逃不掉」。
個人習慣——你自己在哪台機器都想要的存檔 lint、格式化。反正這是你的 home 目錄，跟著你走。

該留在專案（.kiro/hooks/）：

跟這個 repo 的技術棧綁死的檢查——某專案用特定 linter、特定測試指令，換個專案就不適用。
要跟團隊一起版控、隨 repo 分發的規範——放進專案目錄才能 commit 進 git，讓 clone 的人自動拿到；放你的 home 目錄，別人看不到。

要小心的坑：

全域 PreToolUse + exit 2 是會真的擋下 agent 動作的。一條寫太緊的全域規則，會讓你每個專案都卡住，debug 起來還不容易聯想到是全域那份。上線前先在單一專案驗過再升全域。
別忘了 30 秒 timeout。全域跑的重檢查（例如整包依賴掃描）超時會被當失敗；除了 PreToolUse exit 2，失敗預設是放行的，等於防護悄悄失效。要嘛拉高 timeout_ms，要嘛把重活挪到非阻塞的 PostToolUse。

對工程團隊的意義

把這一版翻成可操作的三件事：

把「每個 repo 都在複製」的 hook 收斂成單一事實來源。 盤點一下你現在各專案裡重複的 lint／掃描／審批 hook，挑出「跨專案都該有」的那幾條，搬進 ~/.kiro/hooks/。改一次、全機生效，也少了「新專案忘了帶」的破口。
用 exit 2 建真正的閘門，而不是只發警告。 很多人的 hook 只是印訊息、不擋事（其他 exit code 一律放行）。如果你要的是「沒過就不准做」，記得那是 PreToolUse + exit 2 的專利，別掛錯事件。
把 Introspect 當團隊的 hook／agent 語法助手。 新人不必先啃完文件才會寫 hook——在 kiro-cli --v3 裡叫 Introspect 生範本、解釋欄位，再讓資深的人 review。降低了「會用 Kiro 進階功能」的門檻。

一句話總結 2.13：Global Hooks 把「設定一次、到處生效」變成預設；Introspect 則把「不會寫」這件事，變成在 CLI 裡問一句就好。 兩個小功能，合起來把 Kiro 的 hook／agent 客製化門檻往下砍了一截——值得實測的點，是把你最常複製的那條 hook 升成全域，看看跨專案體驗差多少。

來源

Kiro CLI Changelog 2.13.0（AWS Kiro 官方，2026-07-17）：https://kiro.dev/changelog/cli/2-13/
Kiro CLI Hooks 文件（事件類型、STDIN 欄位、exit code、matcher）：https://kiro.dev/docs/cli/hooks/
Kiro CLI Subagents 文件（toolsSettings.subagent、availableAgents／trustedAgents、呼叫方式）：https://kiro.dev/docs/cli/chat/subagents/
Kiro CLI Changelog 總覽（2.12 MCP OAuth、CLI 3.0 --v3 早期存取範圍）：https://kiro.dev/changelog/cli/