Show HN: 並列AIコーディングセッションによるハンドオフファイルの上書きを防止

多くのAIコーディングアシスタントには、セッションの状態をMarkdownファイルに保存して、圧縮後や新しいセッションでコンテキストを復元する「ハンドオフ」機能があります。しかし、既存のツールは並列セッション間の競合をほとんど考慮していません。同じリポジトリで2つのセッションが同時に動作したり、別のマシンでセッションを復元する際にバックグラウンドエージェントが動作していると、ハンドオフファイルが互いに上書きされ、コンテキストが失われます。

「claude-handoff-guard」というオープンソースプロジェクトは、ファイル内所有権メカニズムによってこの問題を解決します。各ハンドオフファイルの最初の行には、作成したセッションのIDが含まれています。このマーカーはGitを通じてファイルとともに移動し、外部のロックファイルは不要です。

鍵となるのはPreToolUseフックです。ファイル書き込み操作の前に、フックは現在のセッションIDを読み取り、ディスク上のファイル内容のマーカーおよび書き込もうとしている内容のマーカーと比較します。不一致があれば書き込みをブロックします。興味深い点として、モデルは自身のセッションIDを直接取得できません。そこで、新しいハンドオフファイルへの初回書き込みは意図的に失敗し、エラーメッセージにセッションIDを含めて返します。モデルはそれをコピーして最初の行として挿入し、再試行します。これにより、新しいファイルごとに一度だけのハンドシェイクが行われます。

保護はすべてのファイル変更経路をカバーします。書き込み操作では新しい内容のマーカーを検証し、編集操作ではディスク上のマーカーをチェックし、シェルリダイレクト（>、>>、tee、sed -i）もブロックします。さらに、このフックはClaude CodeとGemini CLIの両方のツールスキーマをサポートしており、片方だけを保護して他方を無視することを防ぎます。

プロジェクトには補助的なフックも含まれています。セッション開始時には既存のハンドオフファイルを一覧表示し、スラッグの重複を検出します。停止時にはハンドオフファイルがない場合に一度だけ通知します。Gitプリコミットフックは、2つのセッションのハンドオフファイルが混在するコミットをブロックします。移行スクリプトやテストスイートも提供されています。

設計哲学は「フェイルオープン」であり、すべてのフックは内部エラーをキャッチして0で終了するため、フックのバグがセッションを妨げることはありません。ユーザーは環境変数や一時ファイルを使って制限をバイパスできますが、その動作はログに記録されます。

著者は次の限界を認めています。意図しない上書きは防げますが、意図的な上書きは防げません。ファイル名のトークンと実際のブランチの一致はチェックしません（クロスデバイス復元を意図的に許可）。非常に稀なTOCTOU競合条件が存在します。プロジェクトはMITライセンスで公開されています。