explain は、CC Safety Net がコマンドを解析する過程を手順ごとに表示します。コマンドがブロックまたは許可される理由や、カスタムルールの適用のされ方を確かめるときに使います。
explain のオプション
--json のスキーマ、ExplainResult のフィールド、TraceStep の全種類は、explain トレースリファレンスを参照してください。
ツールが実行するシェルとしてコマンドを読み取る
explain の既定のシェルモードは auto で、PowerShell に見えるコマンドは PowerShell として読み取ります。ただし、エージェントのツールは別のシェルを実行していることがあります。Claude Code の Bash ツールは POSIX を実行するため、auto のままだとフックが出していない判定を報告することがあります。
bash の
rmdir は空のディレクトリしか削除しないため、Bash ツールからのこの呼び出しはフックでは許可されます。--shell posix を付ければ、その許可を再現できます。このフラグはコマンドの解析方法と適用されるシェルのルールの両方を切り替えるので、判定を再現したいツールの方言を指定してください。
--shell powershell では、引数を分けて渡したコマンドを PowerShell の引用規則で連結するため、その中のアポストロフィは POSIX のエスケープではなく二重化されます。それ以外の方言では POSIX のエスケープのままです。
parse ステップには、解析に使った方言の語が表示されます。auto では、PowerShell の読み取りが判定を決めた場合でも POSIX の語が表示されるため、Windows のパスはバックスラッシュが落ちた形になります。
auto、posix、powershell 以外の値を渡すと、エラーと使用方法の行を出力して 1 で終了します。
ダッシュで始まるコマンドを explain する
-- でオプションの解析が終わり、その後ろはすべてコマンドとして扱われます。そのため explain -- --help はヘルプを出力せず、リテラルのコマンド --help を解析します。| や && などのシェル演算子をコマンドに残すには、コマンド全体を 1 つの引数として引用符で囲みます。
explain の終了コード
explain は、結果がブロックでも許可でも 0 で終了します。終了コードではなく result フィールドを読んでください。1 で終了するのは、不明なオプション、存在しない --cwd パス、不明な --shell の値といったオプションエラーの場合と、解析を拒否したコマンドの場合です。
explain が解析を拒否するコマンド
CC Safety Net の解析上限を超えるコマンドや、echo ${ のようにパーサーが構文を受け付けないコマンドは、explain が解析を拒否します。このとき 1 行のエラーを出力して 1 で終了します。--json を付けると、標準出力にはエラーオブジェクトだけが出力されます。