跳轉到主要內容
Hooks 讓您在特定代理事件發生時自動執行 shell 指令——例如，在工具寫入檔案前強制執行程式碼規範，或記錄每次完成的回合。此系統遵循與 Claude Code hooks 相同的慣例。

​
設定

Hooks 透過兩個層級的 JSON 檔案設定：
範圍檔案管理方式
全域~/.bricks-project-desktop/hooks.json設定 > 代理 > Hooks 設定 > 開啟
專案<project>/.bricks/hooks.json直接編輯
兩個檔案會疊加合併。相同的處理器（同一事件、比對器和指令）會自動去重。

​
設定格式

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash|write_file",
        "hooks": [
          {
            "type": "command",
            "command": "node check.js",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
最外層的 hooks 包裝是可選的——您也可以將事件鍵值直接放在根層級。 每個事件鍵值對應一個規則物件陣列。規則包含：
  • matcher — 要比對的工具或觸發器（參見 比對器）
  • hooks — 處理器物件陣列，每個包含：
    • type — 固定為 "command"
    • command — 要執行的 shell 指令
    • timeout — 每個處理器的逾時秒數（預設 60）

​
比對器

比對器遵循 Claude Code 語意：
模式行為
空值或 *比對所有項目
僅包含文字字元和 |精確的管線分隔清單（例如 bash|write_file）
其他任何值視為正規表達式

​
事件

事件比對器值可阻擋說明
SessionStartstartup | resume否工作階段啟動或恢復時觸發
UserPromptSubmit—是在使用者提示送出前執行；可拒絕該提示
PreToolUse工具名稱是在工具呼叫前執行；可拒絕該呼叫
PostToolUse工具名稱否在工具呼叫後執行；可附加回饋
Stop—否代理完成回合時觸發
SubagentStart代理名稱否子代理生成時觸發
SubagentStop代理名稱否子代理完成時觸發
PreCompactmanual | auto否上下文壓縮前觸發
PostCompactmanual | auto否上下文壓縮後觸發
GoalUpdateset | evaluated | complete | cancel否目標生命週期變更時觸發

​
執行協定

每個比對到的處理器會透過 shell 執行，cwd 設定為專案路徑。stdin 會傳入一個 JSON 承載，包含：
  • session_id — 目前的工作階段 ID
  • cwd — 專案路徑
  • hook_event_name — 事件名稱
以及依事件不同的欄位，如 tool_name、tool_input、tool_response、prompt、trigger、agent_type 和 goal。 以下環境變數會被設定：
變數值
BRICKS_PROJECT_DIR專案路徑
BRICKS_SESSION_ID目前的工作階段 ID
BRICKS_HOOK_EVENT事件名稱

​
結束代碼

結束代碼行為
0成功 — stdout 可包含 JSON 決策（詳見下方）
2阻擋 — stderr 作為阻擋原因
其他非阻擋性失敗 — 記錄後忽略
逾時同樣視為非阻擋性失敗。

​
決策輸出

結束代碼為 0 時，stdout 可包含一個 JSON 物件：
  • 阻擋工具呼叫（PreToolUse）：{"decision": "block", "reason": "..."}
  • 拒絕並附原因（PreToolUse）：{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "..."}}
  • 附加回饋（PostToolUse）：{"additionalContext": "..."}
所有比對到的處理器會平行執行。任一處理器阻擋時，該工具呼叫或提示即被拒絕，所有阻擋原因會合併。

​
適用範圍

Hooks 適用於所有代理情境：
  • 主代理的工具呼叫
  • 子代理的工具呼叫（承載中包含 agent_type）
  • GUI 工具呼叫
  • ACP 工具呼叫
UserPromptSubmit 僅攔截使用者輸入的提示——目標延續和內部工作階段訊息不受影響。 Hook 引擎失敗不會傳播至代理迴圈。

​
範例

​
在檔案寫入前要求 linter 檢查

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write_file",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/lint-check.js"
          }
        ]
      }
    ]
  }
}

​
記錄每次完成的回合

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Turn completed\" >> /tmp/ctor-events.log"
          }
        ]
      }
    ]
  }
}

​
資料儲存

資料位置
全域 hooks 設定~/.bricks-project-desktop/hooks.json
專案 hooks 設定<project>/.bricks/hooks.json