フックの仕組み

フックスーパーバイザーは、AIセッションでアシスタントがあらかじめチームの規約を知っていたかのように振る舞えるようにする、Pathruleの構成要素です。ローカルで動作し、キャッシュから読み込み、アシスタントが最初のアクションを起こす前に関連するメモリとルールを届け、スキルを名前で提示します。スキルの指示内容は、そのスキルを呼び出したときに届きます。

このページでは、ユーザー視点で仕組みの全体像を説明します。ランタイム内部の詳細には踏み込みません。

フックとは

フックとは、AIクライアントがターン内の明確に定められたタイミングで呼び出す小さなスクリプトです。Pathruleは、各クライアントが実際に公開している配信イベントと適用イベントを利用します。

• SessionStartは、アシスタントが作業しているワークスペース、Pathruleのプロトコル、チームのコンテキストを、セッションごとに1回渡します。
• UserPromptSubmitは、プロンプトイベントでコンテキストを受け付けるクライアントで、次のターンの範囲を絞り込みます。
• PreToolUseは、クライアントが受け付ける場合に、アクションの前にコンテキストまたは厳格なルールによる判定を渡します。
• PostToolUseは結果を記録します。また、ツール実行前のイベントで判定は受け付けてもコンテキストは受け付けないクライアントでは、パス単位のコンテキストを補う役割も担います。
• Stopイベントとセッション終了イベントがターンを締めくくります。Claude CodeとCodexでは、人が承認した必須チェックがある場合、そのコマンドが成功するまでここでターンを終了させずに保持できます。

pathrule setupとpathrule sync、またはVS Code拡張機能が、Claude Code、Codex、Cursor、GitHub Copilotにこれらのフックを登録します。WindsurfにはPathruleのフックがないため、生成されたルールファイルがセッションのブートストラップを担い、ローカルMCPサーバーが必要に応じてより深いコンテキストを提供します。

クライアントごとの配信方式

厳格なルールとは、人が承認したブロックパターンを持つルールのことです。何がブロックされ、何が情報提供にとどまるかについては、ガードレールとしてのルールを参照してください。

フックが行うこと

フックスーパーバイザーは、次の4つの処理を順に行います。

1. パスを解決する。作業ディレクトリをワークスペースのノードに対応付けます。
2. キャッシュを読み込む。ローカルキャッシュには、そのパスに対応するメモリ、ルール、スキルの事前計算済みインデックスが保持されています。
3. スライスを形づくる。意図に合った深さを選びます。UIの微調整には最小限のペイロード、バグ修正やリファクタリングには焦点を絞ったペイロードを返します。探索的なプロンプトでは、より深いペイロードが使われます。
4. ペイロードを返す。テキストは、次のアクションのためのシステムコンテキストとしてクライアントに返されます。

ローカルモードでは、この一連の処理がすべて手元のマシン上で完結します。Cloudワークスペースでは、意味に基づいてナレッジの優先順位を付けるために、プロンプトフックがプロンプトの冒頭部分（おおよそ最初の1,000文字）をPathrule Cloudにも送信します。その呼び出しが遅い場合や失敗した場合、フックはローカルインデックスとの照合にフォールバックするため、ネットワークの問題があってもターンがコンテキストなしになることはありません。

表示される内容

アシスタントのコンテキスト表示（エディタが公開しているもの）に、Pathruleのセクションが追加されます。そこには次の内容が並びます。

• フックが解決したパスと、作業対象である可能性が最も高いパス。これはアシスタントが検索を始める前に開くよう求められる経路で、実際に開いたかどうかをPathruleが記録します。
• 一致するルールとその優先度。
• プロンプトに最も関連するメモリ。アシスタントがそのまま活用できるよう、本文全体が届きます。確度の低い一致はタイトルとidとして届き、必要に応じて全文を読めます。
• このスコープに合うスキル。名前で示され、::skill-nameですぐに呼び出せます。

現在のパスについて新しく関連する情報がない場合、フックは何も追加しないため、静かなターンではコンテキストを消費しません。

2つの配信チャネル

ナレッジは、役割の異なる2つのフックチャネルを通じてアシスタントに届きます。

• プロンプトごとのチャネルは、プロンプト送信フックを持つクライアント（Claude CodeとCodex）で、プロンプトを送信したときに1回実行されます。深い情報を担うのはこちらのチャネルで、プロンプトに合うルール、最も強く一致するメモリ（アシスタントがそのまま活用できる本文全体）、関連がありそうなスキル（名前で提示）を届けます。スキルは手順なので、指示として押し込まれることはありません。スキルの本文全体は、::skill-nameで呼び出したときに届きます。
• ツール呼び出しごとのチャネルは、ファイル操作やシェル操作の前後に実行され、1回のターンで何度も動きます。意図的に軽量に保たれており、操作対象のパスに適用されるルールとメモリの名前と1行の要約だけを届けます。これによりアシスタントはそこに何があるかを把握でき、必要なら1回の呼び出しで本文を読めます。

Claude CodeとCodexでは、プロンプトのチャネルとツール実行前のチャネルの両方がアシスタントに届きます。CursorとGitHub Copilotはプロンプトイベントでコンテキストを受け付けないため、セッション開始フックがブートストラップを、ツール実行後のフックがパス単位の名前を届けます。

どちらのチャネルも同じ内容を繰り返しません。セッション内ですでに届けた本文は再送されず、編集された本文は次に必要になったときに改めて届きます。

ディスクに残るもの

Pathruleのフックがインストールされているクライアントは、プロトコルとチームのコンテキストを指示ファイルではなくセッション開始フックから受け取ります。Claude Codeでは、セッション開始時のコンテキストがシステムプロンプトに組み込まれるため、会話のコンパクション後も失われません。指示ファイル(CLAUDE.md、AGENTS.md、Cursorのルール、Copilotの指示ファイル)にはPathruleに関する短い注記だけが残り、以前のバージョンでPathruleが書き込んだプロトコルのコピーやディレクトリごとのナレッジファイルは削除されます。これらのファイルに含まれる自分で書いた内容はそのまま残ります。

次の2つのケースでは、コンパイル済みファイルが維持されます。

• WindsurfのようにPathruleのフックがないクライアントや、フックがインストールされていないクライアントでは、プロトコル全体とパスごとのナレッジファイルが維持されます。ほかに届ける手段がないためです。
• 以前のバージョンのPathruleが自分の指示ファイルをバックアップに移動し、まだ復元されていない場合、そのバックアップが処理されるまでPathruleはファイル全体を維持します。自分の指示が別の場所にある状態で短い注記だけを目にすることがないようにするためです。

フックをインストールしたままコンパイル済みファイルを維持したい場合は、Pathruleランタイムの環境でPATHRULE_SIGNATURE_MODE=offを設定してください。

フックだけでは足りないとき

フックは一般的なケースを想定して設計されています。さらに情報が必要な場合、アシスタントはいつでもMCPツールを使えます。

• 探索的なプロンプト（「billingについてわかっていることをすべて挙げて」など）では、アシスタントがpathrule_get_contextを直接呼び出します。
• メモリの本文全体が必要な場合は、フックで示されたidを指定してpathrule_read_memoryを呼び出します。
• 書き込み（ユーザーが規約やルールの保存を求めた場合）には、対応する書き込みツールを使います。

フックは高速な経路、MCPは深い経路です。どちらも同じ信頼できる情報源を共有しています。

パス単位のスコープで小さく保つ

フックが返すスライスは、作業ディレクトリに応じて形づくられます。

• apps/web/dashboardでの変更では、データベースマイグレーションに関するルールは読み込まれません。
• services/billing/webhooksでの変更では、billingのルールとWebhookリプレイのスキルが読み込まれ、マーケティングサイトの規約は読み込まれません。
• リポジトリのルートでの探索的なプロンプトでは、すべての本文ではなくワークスペースの概要が読み込まれます。

すべてのセッションが丸ごと読み込む単一のグローバルな指示ファイルと比べて、届けるコンテキストを小さく保てるのは、このパス単位のスコープがあるからです。

何も表示されないとき

セッションを開いてもPathruleのセクションが空の場合は、doctorを実行してください。

pathrule doctor

doctorは読み取り専用で、次の項目を確認します。

• サインインの状態、組織、ワークスペース。
• 現在のフォルダがワークスペースに紐づけられているかどうか。
• 各AIクライアントにPathruleのMCPエントリがインストールされているかどうか。
• フォルダ内にあるPathrule管理下のファイルと、それらを書き込んだPathruleのサーフェスおよびバージョン。

対応が必要な項目がある場合、出力の最後に次に実行すべきコマンドが表示されます。--jsonを付けると完全なレポートが出力され、Nodeのバージョンも確認されるほか、すでに存在しないランタイムを指しているMCPエントリも検出されます。

ローカルの構成要素を元の状態に戻すには、次を実行します。

pathrule repair

repairは、古くなったMCPエントリを書き直し、フックスクリプトと各クライアントのフック登録を再インストールし、関連ファイルとフックが読み込むローカルキャッシュを再同期したうえで、もう一度doctorを実行します。

Pathruleのフックをすべて一度に無効にしたい場合は、~/.pathrule/kill-hooksを作成してください。次のフック呼び出しからは何もせずにそのまま通過します。フックを再び有効にするには、このファイルを削除します。

次に読むもの

• MCPの概要：深い経路を支えるツール群について。
• 基本概念：フックが読み込むデータモデルについて。
• CLIのインストール：フックスーパーバイザーをホストするランタイムのインストールについて。