FileChanged フック

FileChanged を使用して、Qwen Code、シェルコマンド、エディター、またはその他のプロセスによって変更されたファイルを監視します。ローカルの非 managed セッションで実行されます。フックの設定、executor、および信頼ルールについては Hooks ガイド を参照してください。

イベント入力

入力には 共通のフックフィールド と以下が含まれます。

{
  "file_path": "/home/me/work/demo/.envrc",
  "event": "change"
}

file_path は絶対パスです。event は監視対象ファイルの追加、変更、削除に対してそれぞれ add、change、unlink です。共通の session_id と cwd はリスニングセッションに属し、書き込み元を識別するものではありません。共有ディレクトリを監視している複数のセッションが、それぞれその変更を受け取ることができます。ファイルの内容は含まれません。

ファイルイベントのみが配信されます。ディレクトリ自体の addDir および unlinkDir イベントは配信されません。監視対象ルート自身のライフサイクルを追跡するインテグレーションは、ファイルシステム状態を確認し（例: stat を使用）、独立して reconciliation を行う必要があります。子ファイルの unlink は、ルートが削除されたことを証明するものではありません。

作業ディレクトリ内のファイル名を監視する

FileChanged フックを追加し、リテラルのファイル名を | で区切って指定します。

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "name": "configuration-changed",
            "command": "node \"$QWEN_PROJECT_DIR/.qwen/hooks/on-file-changed.mjs\""
          }
        ]
      }
    ]
  }
}

これにより、セッションの cwd に .envrc と .env が登録されます。静的登録はグロブを展開したり、ディレクトリを再帰的にスキャンしたりしません。マッチャーが省略または空の場合、*、および .* は静的パスを登録しません。これらのフックは、動的パスを含む、セッションの監視パスからのイベントを受け取ります。イベントはファイルのベース名に対して 既存のマッチャールール を使用してフィルタリングされます。

正規表現パターンはすでに監視対象のパスをフィルタリングします。ファイルやディレクトリは watchPaths を通じて明示的に登録してください。

静的ルートはドットファイルを含むベアのりテラルファイル名のみを受け付けます。正規表現/グロブのメタ文字とパス区切り文字は静的ルートを作成しません。既存のディレクトリと検査できないパスは除外されます。存在しないファイルは作成のために監視される場合があります。静的ファイル探索は、関係ないエントリを除外しながら親ディレクトリを監視します。再帰的ディレクトリには明示的な watchPaths を使用してください。セッションの作業ディレクトリを変更すると、再配置が完了する前に静的ルートが再配置されます。明示的な絶対動的ルートは変更されません。

cwd 外のディレクトリとパスを監視する

成功した同期 SessionStart フックは、hookSpecificOutput.watchPaths を通じて絶対ファイルやディレクトリを登録できます。ディレクトリは後から作成される子も含めて再帰的に監視されます。再帰的探索は .git と node_modules のサブツリーをスキップします。内部のパスを監視するには、そのファイルまたはディレクトリを明示的に登録してください。特別なファイルタイプは無視され、通常のディレクトリに深さ制限はありません。初期登録は SessionStart が戻る前にウォッチャーの準備完了を待ちます。

再帰的探索は、<target>.<12 lowercase hex characters>.tmp という名前のアトミック書き込み一時ファイルを無視します。遅延リネームや孤立ファイルも含まれます。このようなファイルを明示的に登録すると、引き続き監視されます。この接尾辞を持つディレクトリは走査可能であり、他の .tmp ファイルは通常通り監視されます。

たとえば、memory フォルダーを登録します。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "name": "watch-memory-folders",
            "command": "node \"$QWEN_PROJECT_DIR/.qwen/hooks/watch-memory.mjs\""
          }
        ]
      }
    ],
    "FileChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "name": "memory-file-changed",
            "command": "node \"$QWEN_PROJECT_DIR/.qwen/hooks/on-file-changed.mjs\""
          }
        ]
      }
    ]
  }
}

watch-memory.mjs にこの JSON を stdout に出力させます。例のパスは /memory が表示する実際の絶対フォルダーに置き換えてください。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "watchPaths": [
      "/home/me/.qwen/projects/demo/memory",
      "/home/me/.qwen/memories"
    ]
  }
}

FileChanged フックにはマッチャーがないため、登録されたディレクトリ全体の変更を受け取ります。ハンドラーは stdin からイベント JSON を読み取ります。自身の書き込みでハンドラーをトリガーしないように、ログや同期の宛先は監視パス外に選択してください。

動的パスを更新する

同じファイルシステム内の複数のワークスペースの場合、すべての実際の memory ディレクトリを 1 つのリストに登録します。リスニングセッションの cwd ではなく、file_path と独自のディレクトリからワークスペースへのマッピングを使用して通知をルーティングしてください。独立したセッションが同じ共有ルートを監視できるため、ビジネスハンドラーで作業を重複排除してください。別のコンテナーやリモートインスタンス内のルートは、そのファイルシステムオーナー内のウォッチャーを必要とします。ホスト上でそのパスを登録しても監視されません。

成功した同期の SessionStart と FileChanged の出力は watchPaths を設定できます。hookSpecificOutput に一致する hookEventName を含めてください。

複数のフックがリストを返す場合、フック実行順序で最後の有効かつ明示的に提供されたリストが優先されます。すべてのエントリは絶対パスでなければならず、1 つでも無効なエントリがあるとリスト全体が無効になります。静的ファイル名登録は、動的置換やクリア後もアクティブなままです。

FileChanged ハンドラーから動的パスをクリアするには、以下を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "FileChanged",
    "watchPaths": []
  }
}

監視の制限

初期ディレクトリスキャンはリプレイされません。登録後に最近の書き込みからのネイティブファイルシステムイベントが届く場合があります。明示的に登録されたシンボリックリンクファイルとディレクトリルートは、祖先パス内のリンクを含めてそのターゲットを監視します。通知は設定されたエイリアスを使用します。1 つのターゲットに複数のエイリアスを登録すると、エイリアスごとに通知が生成されます。リンクのターゲット変更後は登録を更新してください。再帰的ルート内で発見されたシンボリックリンクは走査されません。イベントは書き込みが落ち着いてから報告されます。 監視はベストエフォートです。ファイルシステムの統合、アクセスできないパス、プロセスのダウンタイム、パスの再設定によりギャップが生じる可能性があります。完全に同期されたコピーを必要とするインテグレーションは、初期スキャン、reconciliation、およびリトライを処理する必要があります。ウォッチャーまたはフックの失敗はログに記録され、元のファイル操作は変更されません。

FileChanged は書き込みの拒否や取り消し、またはモデルコンテキストの追加は行えません。明示的に登録されたパスのみが監視されます。memory フォルダーは自動的に登録されず、専用の auto-memory 有効/無効イベントも存在しません。監視対象ファイルに書き込むフックは自身をトリガーする可能性があります。そのような書き込みを避けるか、作業を重複排除してください。

SSH 実行環境、シェルサンドボックスワーカー、および managed ディスパッチャーはローカルファイルシステムウォッチャーを開始しません。通常のフック有効化と信頼ルールは引き続き適用されます。監視は所有セッションがシャットダウンしたときに停止します。