フックリファレンス

フックを使用すると、Qoder CLI のライフサイクルの特定のタイミングでカスタムロジックを自動実行できます。たとえば、ツール呼び出し前の検証、セッション開始時のコンテキスト注入、ファイル変更時の外部プロセスのトリガーなどが可能です。本ページはフックの完全なリファレンスです。利用ガイドについてはフックを参照してください。

イベントタイプ

フックは以下のイベントにバインドできます：

イベント	トリガーされるタイミング
`PreToolUse`	ツール呼び出し前。
`PostToolUse`	ツール呼び出し成功後。
`PostToolUseFailure`	ツール呼び出し失敗後。
`UserPromptSubmit`	ユーザーがプロンプトを送信した時。
`SessionStart`	セッション開始時。
`SessionEnd`	セッション終了時。
`Stop`	メインエージェントが応答を停止した時。
`StopFailure`	停止プロセスが失敗した時。
`SubagentStart`	サブエージェント起動時。
`SubagentStop`	サブエージェント停止時。
`PreCompact`	コンテキスト圧縮前。
`PostCompact`	コンテキスト圧縮後。
`Notification`	通知生成時。
`ConfigChange`	構成変更時。
`InstructionsLoaded`	プロジェクト指示の読み込み後。
`CwdChanged`	作業ディレクトリ変更時。
`FileChanged`	ファイル変更時。
`WorktreeCreate`	ワークツリー作成時。
`WorktreeRemove`	ワークツリー削除時。
`Elicitation`	エリシテーション開始時。
`ElicitationResult`	エリシテーション結果返答時。
`TaskCreated`	タスク作成時。
`TaskCompleted`	タスク完了時。
`PermissionRequest`	アクセス許可の要求開始時。
`PermissionDenied`	アクセス拒否時。
`TeammateIdle`	共同作業者アイドル時。
`Setup`	初期インストール時。

各イベントのマッチャー一致フィールド、stdin の追加入力フィールド、ブロックのサポート有無、および利用可能な hookSpecificOutput フィールドについては、フックの「イベントリスト」セクションを参照してください。

フックタイプ

各フックは type を介して実行方法を指定します：

タイプ	説明
`command`	シェルコマンドを1つ実行します。
`http`	HTTP リクエストを送信します。
`prompt`	独立した単一ターンのモデル呼び出しで判定を行い、モデルは `{ ok, reason }` を返し、`ok=false` はブロックします。
`agent`	サブエージェントを起動して検証を行い、`StructuredOutput` を介して `{ ok, reason }` を返し、`ok=false` はブロックします。

各タイプの完全なフィールド（http の url/headers や、prompt と agent の返却規約など）については、フックの「フックエントリタイプ」セクションを参照してください。

定義構造

フックは settings.json の hooks グループ内でイベントごとに構成されます。各イベントは一組のフック定義に対応します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./scripts/check.sh" }
        ]
      }
    ]
  }
}

フック定義（グループ）フィールド：

フィールド	説明
`matcher`	一致ルール（下文参照）。このフックグループがどのターゲットに適用されるかを決定します。
`hooks`	フックの配列。各項目には `type` と対応するパラメーターが含まれます。

個々のフックエントリは、type およびタイプ固有のパラメーターに加え、name、timeout、if、async（バックグラウンドで実行され、メインプロセスをブロックしない）などのフィールドもサポートしています。完全なリストについては、フックの「フックエントリタイプ」セクションを参照してください。

一致ルール

matcher は、フックがどのターゲット（ツール名など）に適用されるかを決定します：

空または *：すべてに一致します。
正確な値：Bash のように、そのターゲットのみに一致します。
パイプ記号 |：Bash|Edit|Write のような複数値。
正規表現：正規表現による一致をサポートします。

より粒度の細かい if 条件は "ToolName" または "ToolName(arg_glob)" として記述でき、arg_glob ではグロブパターンを使用してツールパラメーターに一致させます。

入力と終了コード

入力（stdin）

フックは stdin を介して現在のコンテキストを含む JSON を受信します（以下は各イベントの共通フィールドです。イベント固有のフィールドについては「イベントリスト」を参照してください）：

フィールド	説明
`session_id`	現在のセッション ID。
`transcript_path`	セッション記録ファイルパス。
`cwd`	現在の作業ディレクトリ。
`hook_event_name`	トリガーされたイベント名。
`permission_mode`	現在の権限モード。
`agent_id`	トリガーされたエージェント ID（該当する場合）。
`agent_type`	エージェントタイプ（該当する場合）。

終了コード

command タイプのフックは終了コードによってフローを制御します：

終了コード	意味
`0`	成功。stdout に JSON を出力して CLI で解析できます。
`2`	ブロック。stderr の内容がフィードバックとしてエージェントに返されます（ブロックをサポートするイベントにのみ適用されます。イベントごとの説明は「イベントリスト」を参照）。
その他	非ブロックエラー。記録されますが、フローは中断されません。

終了コードが 0 の場合、stdout を介して JSON を返すことでよりきめ細かな制御が可能です。完全なフィールド（continue、stopReason、suppressOutput、systemMessage、decision、reason、hookSpecificOutput）については、フックの「フックスクリプトの記述」セクションを参照してください。

プラグイン内のフック

プラグインにはフックを含めることができ、プラグインディレクトリ内の hooks/hooks.json に構成されます。形式は settings.json の hooks グループと同じです。プラグインリファレンスを参照してください。

次のステップ

フック利用ガイド：フック。
拡張機能のトラブルシューティング：フック、MCP、およびプラグインの問題。

​イベントタイプ

​フックタイプ

​定義構造

​一致ルール

​入力と終了コード

​入力（stdin）

​終了コード

​プラグイン内のフック

​次のステップ