> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

> 在代理生命週期事件時執行自訂指令

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

## 設定

Hooks 透過兩個層級的 JSON 檔案設定：

| 範圍     | 檔案                                     | 管理方式                        |
| ------ | -------------------------------------- | --------------------------- |
| **全域** | `~/.bricks-project-desktop/hooks.json` | **設定 > 代理 > Hooks 設定 > 開啟** |
| **專案** | `<project>/.bricks/hooks.json`         | 直接編輯                        |

兩個檔案會疊加合併。相同的處理器（同一事件、比對器和指令）會自動去重。

### 設定格式

```json theme={null}
{
  "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`） |
| 其他任何值         | 視為正規表達式                          |

## 事件

| 事件                 | 比對器值                                           | 可阻擋 | 說明                 |
| ------------------ | ---------------------------------------------- | --- | ------------------ |
| `SessionStart`     | `startup` \| `resume`                          | 否   | 工作階段啟動或恢復時觸發       |
| `UserPromptSubmit` | —                                              | 是   | 在使用者提示送出前執行；可拒絕該提示 |
| `PreToolUse`       | 工具名稱                                           | 是   | 在工具呼叫前執行；可拒絕該呼叫    |
| `PostToolUse`      | 工具名稱                                           | 否   | 在工具呼叫後執行；可附加回饋     |
| `Stop`             | —                                              | 否   | 代理完成回合時觸發          |
| `SubagentStart`    | 代理名稱                                           | 否   | 子代理生成時觸發           |
| `SubagentStop`     | 代理名稱                                           | 否   | 子代理完成時觸發           |
| `PreCompact`       | `manual` \| `auto`                             | 否   | 上下文壓縮前觸發           |
| `PostCompact`      | `manual` \| `auto`                             | 否   | 上下文壓縮後觸發           |
| `GoalUpdate`       | `set` \| `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 檢查

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

### 記錄每次完成的回合

```json theme={null}
{
  "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`         |