システム構成要素
連携 adapter
adapter は、エージェントのツール呼び出し payload を正規化した invocation に変換し、guard の判定をそのエージェントの deny format に変換します。システムレベルでは、次の 2 点が重要です。- adapter がコマンド実行 capability を与えるのは、連携ごとに定めた正確な tool name だけです。unknown tool は shell-command として扱われません。policy-file、Git-metadata、sensitive-path の inspection は引き続き受けますが、その text は command として parse されません。
- adapter は
config-statereporting path を所有します。guard 自身は、この stage を出力しません。
Policy snapshot
loadPolicySnapshot() は、local policy configuration、rulebook lockfile、検証済み rulebook cache entry から、有効な runtime policy を構成します。その contract は内容と同じくらい重要です。
- 書き込み、network request、in-memory caching を行いません。 remote rulebook の同期は、明示的な CLI 操作（
cc-safety-net rule sync）のままです。 - 結果は深く immutableです。policy object、rules array、各 rule とその
block_args、transparent-wrapper list、safety block とその override、destructive-command rule override、allow path、disabled rule と deny path を含む secret-protection block はすべて freeze されます。snapshot wrapper 自身も freeze されます。 - 結果は正確に 2 つの state になります。
readyでは、検証済みのすべての source が適用されます。degradedでは、candidate source が拒否され、代わりに安全なものが適用されます。degraded reason は、失敗した source、active でないもの、修復方法を示します。 - rule ごとの provenance（rulebook name と version、public source spec、override reason）は snapshot に登録され、diagnostics と GUI が表示します。
順序付き guard stage
すべての連携の各ツール呼び出しは、次の固定順序で実行されます。拒否する操作は、audit log に示したfailureStage value を記録します。
この順序から、次の 3 点が直接導かれます。
- stage 6 と 7 は stage 8 より前に実行します。 Policy-file protection と Git-metadata protection は、設定を読み込む前に拒否します。常に有効で、config state を持たず、preset、override、master switch で弱めることはできません。
- Sensitive-path protection は snapshot の後、command analysis の前に実行します。 3 つの hard-stop protection のうち、policy が制御できるのはこれだけです。master switch、pattern ごとの override、deny path で制御します。
- stage 8 より後の判定だけが safety level を報告します。 input bound、policy-file protection、Git-metadata protection による拒否には、意図的に
levelと config-fallback metadata がありません。その時点では、どちらもまだ不明なためです。
Command analysis の内部
stage 12 で classifier を実行します。shell operator で command を segment に分割し、各 segment を個別に調べます。1 つでも block すると command 全体を拒否します。 engine は、segment 間の working-directory change（cd と pushd）を追跡し、environment assignment を伝播します。このため、target classification は実際の shell の動作を反映します。shell wrapper と interpreter body への recursion は最大 10 level です。各 analyzer、safety-level boundary、完全な target-classification order は解析エンジンを参照してください。
Parser と runtime dependency surface
parseCommand(source, dialect, limits) は、CC Safety Net 独自の POSIX parser または独自の PowerShell parserに dispatch します。auto dialect は、適用するものを判定します。どちらも内部 module であり、third-party grammar の wrapper ではありません。
Parser と analyzer の budget は compile-time constant で、policy setting ではありません。そのため、設定で増やすことはできません。
最初の 3 つは initial parse を制限します。4 番目は parse 後に analyzer が command から派生させる作業を制限します。対象は、
find -exec、xargs、parallel から再構築した child command、wrapper の後ろに埋め込まれた command、analyzer に replay する tracked heredoc file、PowerShell Invoke-Expression source です。使い切ると、"Command analysis exceeds CC Safety Net's derived-command work limit. Reduce nested or embedded command complexity and retry." という reason で拒否します。これは recursion-depth limit と、上の stage table にある structural validation limit とは異なる failure です。
analyzer の public contract は意図的に狭くしています。allow では何も返さず、block では result object を返します。parser 内部の complete / partial / limited state は公開しないため、caller は parse confidence で分岐できません。
PowerShell support は Remove-Item とその alias、および既存の cross-shell rule を中心とする保守的な subsetです。その subset について、native quoting、path separator、connector、pipeline、dynamic-word provenance を保持します。汎用 PowerShell interpreter ではありません。
Dependency
CC Safety Net の runtime package dependency はzod 1 つだけで、configuration validation のみに使います。createRequire で遅延読み込みするため、configuration を実際に validate する場合だけ cost が発生します。Node bundle と Pi bundle では external のままにして、installed package から解決します。import する source module は正確に 1 つです。
公開 bundle は third-party shell parser を含みません。path scanner が読み取る flat entry stream は、projectShellSyntax により parsed IR から投影します。このため、上記の内部 POSIX parser と PowerShell parser が唯一の shell structure source です。raw command text を 2 回目に tokenize して drift することはありません。
公開 runtime target は Node.js 18 以降です。
主な設計特性
- すべての連携で 1 つの固定順序。 上の stage table が contract 全体です。guard には agent ごとの branch がありません。
- 常時有効な保護を設定より前に実行。 Policy-file protection と Git-metadata protection は、無効化できる policy を読み込む前に拒否するため、無効化できません。
- guard 自身の failure で fail closed。 dependency の throw、parser budget の枯渇、tool-input bound の違反は、allow ではなく deny になり、失敗した stage に属します。無効な設定は別の場合で、deny しません。設定の復旧を参照してください。
- 評価時に network も write もない。 runtime 評価は network request を行わず、snapshot loader は write しません。guard は外向き通信を検査または filter しません。
- Platform-agnostic core。 adapter が format を変換し、guard と classifier はそのまま共有されます。
- 上限付きであり、網羅的ではない。 これは静的な実行前ポリシーゲートで、OS sandbox、privilege boundary、インストール済み連携を回避する command に対する保護ではありません。既知の制限を参照してください。
次に読むページ
技術ガイドは、ユーザー向けの lifecycle から設計理由まで順に説明します。このページは step 3 です。- 前：連携アーキテクチャ：各 agent call が上記の adapter に到達する仕組み。仕組み：同じ順序をユーザー向けの深さで説明します。
- 次：解析エンジン：stage 12 の詳細。各 analyzer、safety-level boundary、recursive-delete classification order を説明します。
- その次：設計原則：order、always-on protection、owned parser を採用した理由を説明します。
ready と degraded。セキュリティモデル：trust boundary。既知の制限：この設計で対応できない範囲。