CC Safety Net を自作のエージェントやハーネスに組み込む

​

プロセス内のチェックか、インストール済みの hook か

​

組み込み時のポリシー解決

• ユーザースコープ：~/.cc-safety-net/policy.json と ~/.cc-safety-net/rules/。CC_SAFETY_NET_HOME が設定されていればその場所に移ります。これは運用者自身のベースラインで、すべての呼び出しに適用されます。
• プロジェクトスコープ：<cwd>/.cc-safety-net/policy.json と <cwd>/.cc-safety-net/rules/。渡したパスそのものから解決され、親ディレクトリをさかのぼる探索は行いません。セッションのサブディレクトリを追跡するホストは、リポジトリのルートを cwd として渡してください。そうしないと、コミットされたプロジェクトポリシーが読み込まれません。
• マージ：プロジェクトファイルはユーザーファイルの上にフィールド単位で重なります。両スコープの保護対象パスのリストは和集合になり、プロジェクトファイルの audit は無視され、プロジェクトが緩めたフィールドは黙って適用されるのではなく報告されます。マージの仕様はポリシーが持っています。
• 環境変数：CC_SAFETY_NET_LEVEL と各機能のスイッチは呼び出しのたびに process.env から読まれ、レベルはポリシーファイルの設定より引き上げることしかできません。環境変数を参照してください。

​

API が保証するもの

• 入力の形 { command, cwd }（cwd は絶対パスのディレクトリ）と、2 つの結果の kind、すなわち allow と、reason 文字列および省略可能な ruleId を持つ deny。
• deny はコマンドを実行してはいけないという意味で、throw も同じ意味です。throw が allow になることはありません。
• cwd がポリシー解決の基準になります。コマンド内の相対パスも、プロジェクトの .cc-safety-net/ 設定も、渡した cwd を基準に解決され、process.cwd() は使われません。
• API のパスは監査レコードを書かず、ネットワークリクエストも行いません。呼び出しが読むのはローカルのポリシーファイル、ファイルシステムの状態、環境設定で、マシンの外には何も出ません。

​

実装例：プラグインホスト

import { checkCommand } from 'cc-safety-net/api';

export function registerSafetyNet(host: PluginHost) {
  host.beforeToolCall((call, ctx) => {
    if (call.toolName !== 'shell') return undefined;

    if (typeof call.input.command !== 'string' || call.input.command.trim() === '') {
      return { block: true, reason: 'Malformed shell tool call.' };
    }

    try {
      const result = checkCommand({ command: call.input.command, cwd: ctx.projectRoot });
      if (result.kind === 'deny') return { block: true, reason: result.reason };
      return undefined;
    } catch (error) {
      console.error('CC Safety Net could not check the command', error);
      return { block: true, reason: 'Command check failed. The command was not executed.' };
    }
  });
}

• チェックするのはコマンド系ツールだけです。checkCommand が解析するのはシェルコマンドの文字列です。ホストの read、write、search といったツールはコマンド系ツールではないので、shell ツールだけを渡し、他はそのまま通してください。
• **cwd は絶対パスのプロジェクトルートです。**ホスト側の呼び名が何であれ、その値がプロジェクトポリシーを選び、コマンド内の .env のような相対パスの基準になります。
• throw はブロックです。catch は契約の fail-closed 側です。投げられたエラーをそのまま実行に進ませるホストは、壊れたチェックを allow に変えてしまいます。
• **不正なイベントもブロックです。**同梱のプロセス内連携はまさにこう動きます。command フィールドが欠けている、あるいは文字列でないイベントは、スキップではなくブロックされます。解析する対象が存在しないからです。

​

運用上の注意

• **ログは自分のものです。**このパスでは監査レコードが書かれないので、ホストが記録しない拒否は何も残りません。logs コマンドと GUI のダッシュボードが表示するのは hook とプラグインの判定であって、組み込み実行のものではありません。
• **運用者は通常のツールで設定します。**組み込みホストも同じポリシーファイルを読むため、status、doctor、explain はそのままホストの挙動の説明になります。ただし、cwd として渡すのと同じディレクトリで実行した場合に限ります。なぜブロックされたのかを聞かれたら、explain トレースを案内してください。
• **ruleId は診断用です。**表示する、記録する、ルールを引くために使う。いずれも問題ありませんが、分岐条件にはしないでください。
• **呼び出しは同期です。**まとめて処理したいならループで回してください。非同期版もバッチ版もありませんし、追加したところで呼び出しがすでに行っているファイル読み取りを隠すだけです。
• バージョンはパッケージから読めます。cc-safety-net/package.json はエクスポートされたサブパスなので、依存関係のバージョンを報告するホストはこれも含められます。

​

関連ページ

• ライブラリ API：checkCommand の完全なリファレンス。
• 連携アーキテクチャ：ホストが自分でコマンドを実行する場合に、この関数が置き換えるインストール済み連携。
• ポリシーと環境変数：呼び出しが読むものすべて。
• ブロックされるコマンド：deny になり得るものの一覧。