> ## 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.

# フック

> エージェントのライフサイクルイベントでカスタムコマンドを実行する

フックを使用すると、特定のエージェントイベント発生時にシェルコマンドを自動的に実行できます。例えば、ツールがファイルを書き込む前にコーディング規約を強制したり、完了した各ターンをログに記録したりできます。このシステムは Claude Code フックと同じ規約に従います。

## 設定

フックは2つのレベルのJSONファイルで設定します：

| スコープ       | ファイル                                   | 管理方法                         |
| ---------- | -------------------------------------- | ---------------------------- |
| **グローバル**  | `~/.bricks-project-desktop/hooks.json` | **設定 > エージェント > フック設定 > 開く** |
| **プロジェクト** | `<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` — 実行するシェルコマンド
  * `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` | いいえ   | ゴールのライフサイクル変更時に発火          |

## 実行プロトコル

マッチした各ハンドラーはシェル経由で実行され、`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": "..."}`

マッチしたすべてのハンドラーは並列で実行されます。いずれかのハンドラーがブロックすると、ツール呼び出しまたはプロンプトは拒否され、すべてのブロック理由が結合されます。

## 適用範囲

フックはすべてのエージェントコンテキストに適用されます：

* **メインエージェント**のツール呼び出し
* **サブエージェント**のツール呼び出し（ペイロードに `agent_type` を含む）
* **GUIツール**の呼び出し
* **ACPツール**の呼び出し

`UserPromptSubmit` はユーザーが入力したプロンプトのみをゲートします。ゴール継続や内部セッションメッセージはインターセプトされません。

フックエンジンのエラーはエージェントループに伝播しません。

## 例

### ファイル書き込み前にリンターチェックを要求

```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"
          }
        ]
      }
    ]
  }
}
```

## データストレージ

| データ         | 場所                                     |
| ----------- | -------------------------------------- |
| グローバルフック設定  | `~/.bricks-project-desktop/hooks.json` |
| プロジェクトフック設定 | `<project>/.bricks/hooks.json`         |