global-agent-guardrails

グローバルエージェントのガードレール

実行前に、壊滅的なシェルコマンドをブロックします。1 つのパターンファイルを、共有フックスクリプトまたは各エージェント用のネイティブアダプターで使用します。これは事故を防ぐものであり、悪意のあるエージェントを防ぐものではありません（python -c "shutil.rmtree(...)" のような難読化は正規表現をすり抜ける可能性があります）。

Cloudroom は、この仕組みに基づくコマンドガードを標準搭載しており、デフォルトで有効になっています。

ファイル構成

セットアップは、共有パターンリスト、ガードスクリプト、テストスイート、エージェント固有のアダプターで構成されます。これらは、各ツールの適切なユーザーレベルの設定場所に配置してください。

インストールの確認

共有ガードとパターンが存在することを確認してから、テストスイートを実行します。失敗がないことが報告されるはずです。

見つからない場合は、プロジェクトのドキュメントにある配線手順に従って再構築してください。

パターンの追加または調整

1. 共有パターンファイルを編集します。POSIX ERE（grep -E）を使用してください。\s は使わず、[[:space:]] を使用します。アダプターによっては、JS/Python 向けに [:space:] を \s に変換し、複数行モードでコンパイルする場合があります。
2. テストスイートにブロックケースと許可ケースを追加してから実行し、すべて合格することを確認します。
3. 各アダプターの正規表現エンジンで、新しいパターンがコンパイルできることを確認します。
4. 利用側は、コマンドごとにパターンを再読み込みする必要があります。エージェントがネイティブのブロックリストを使用する場合は、適宜変更を反映してください。

ブロックするのは、壊滅的なコマンド（取り消せないデータ消失、ディスクの消去、リポジトリの削除）のみにしてください。復旧可能なローカルコマンドは許可し、過剰なブロックは避けてください。

エージェントごとの配線（ユーザー共通）

各エージェントは、ドキュメントに記載されたフックまたはネイティブのコマンドブロック機能を使って設定してください。対応している場合は、フックから共有ガードを呼び出すようにします。既存の設定を上書きせず、設定を統合してください。パスの展開方法に一貫性がない場合は、設定で絶対パスを使用してください。

注意点

• フックの信頼性が設定内容に紐付けられているエージェントもあります。フックの設定を変更した後は、エージェントのドキュメントに従って信頼または承認の手続きを行ってください。
• バックグラウンド環境やワーカー環境によっては、ローカルのフックスクリプトを実行できない場合があります。エージェントのドキュメントで、失敗時の動作と制限を確認してください。
• プラグインのフックマニフェスト、有効化方法、失敗時の動作はエージェントによって異なります。アダプターはシンプルに保ち、各ツールの公開ドキュメントに従ってください。
• パターンファイルの破損によって、すべてのコマンドが予期せずブロックされないよう、アダプターでエラーを意図的に処理してください。
• ネイティブのブロックリストの動作はさまざまです。確認を求める項目もあれば、実行を阻止する項目もあります。壊滅的なコマンドには、適切な範囲で最も強力な方法を使用してください。
• ガードが各連携で使われるペイロード形式からコマンドを読み取ることを確認してください。
• アダプターの正規表現では、^ が grep と同様に各シェル行に一致するよう、複数行モードが必要な場合があります。
• 誤検知の種類： 引数のテキストに危険そうな文字列を含む無害なコマンドがブロックされることがあります。回避策として、そのテキストをファイルに入れて参照してください。
• 一部のエージェントやリモート／バックグラウンド実行環境では、ローカルフックがサポートされない場合があります。最新のサポート状況は、該当するエージェントのドキュメントで確認してください。

E2E 検証

一時的な Git 管理外のディレクトリで安全なプローブを実行します。実行されればブロックされるはずのコマンドを、エージェントに実行させてください。ガードによるブロックが示されれば正常に機能しています。リポジトリコンテキストに関するエラーが表示された場合、そのプローブではガードをテストできていません。

壊滅的なコマンドがブロックされることを確認するには、ガードのテストスイートを直接実行してください。