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

​
設定

フックは2つのレベルのJSONファイルで設定します：
スコープファイル管理方法
グローバル~/.bricks-project-desktop/hooks.json設定 > エージェント > フック設定 > 開く
プロジェクト<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 — 実行するシェルコマンド
    • timeout — ハンドラーごとのタイムアウト秒数（デフォルト60）

​
マッチャー

マッチャーは Claude Code のセマンティクスに従います：
パターン動作
空またはは *すべてにマッチ
ワード文字と | のみ正確なパイプ区切りリスト（例: bash|write_file）
その他正規表現として処理

​
イベント

イベントマッチャー値ブロック可説明
SessionStartstartup | resumeいいえセッション開始または再開時に発火
UserPromptSubmit—はいユーザープロンプト送信前に実行。プロンプトを拒否可能
PreToolUseツール名はいツール呼び出し前に実行。呼び出しを拒否可能
PostToolUseツール名いいえツール呼び出し後に実行。フィードバックを追加可能
Stop—いいえエージェントがターンを完了したとき発火
SubagentStartエージェント名いいえサブエージェント生成時に発火
SubagentStopエージェント名いいえサブエージェント完了時に発火
PreCompactmanual | autoいいえコンテキスト圧縮前に発火
PostCompactmanual | autoいいえコンテキスト圧縮後に発火
GoalUpdateset | 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 はユーザーが入力したプロンプトのみをゲートします。ゴール継続や内部セッションメッセージはインターセプトされません。 フックエンジンのエラーはエージェントループに伝播しません。

​
例

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

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

​
データストレージ

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