> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 設定の復旧：ready 状態と degraded 状態

> 設定を検証できないときの CC Safety Net の動作を説明します。ready と degraded の違い、強制され続ける保護、状態の報告のされ方、復旧に使う具体的なコマンドを扱います。

CC Safety Net は、ツール呼び出しのたびにポリシーのスナップショットを読み込みます。読み取る対象は、ユーザーポリシーのファイル、その上に重なるプロジェクトポリシーのファイル、そして両スコープの `rule.json` です。`rule.json` に列挙された rulebook はいずれもライブファイルで、同じ呼び出しの中で `<scope>/rules/<name>/rulebook.json` から読み込まれます。この読み込みでは、書き込みもネットワークアクセスも結果のキャッシュも行わないため、スナップショットは常にディスク上の最新の設定を反映します。

スナップショットの状態は **ready** と **degraded** の 2 つだけです。このページでは、設定元が拒否されたときに失われる保護と、`ready` に戻す手順を説明します。

## 設定の状態

| 状態 | 発生条件 | 意味 |
| - | - | - |
| `ready` | 有効な設定元をすべて読み込み、検証にも成功した | 記述したとおりの設定で通常どおり評価する |
| `degraded` | ルールのエラー、ルールの警告、いずれかのスコープの `policy.json` のエラーのいずれかがある | フォールバックを使って通常どおり評価を続け、すべての表示箇所に、拒否された設定元を示す警告を出す |

警告が 1 つでもあれば、ランタイムは `degraded` になります。エラーと警告の違いは状態の深刻さではなく、その設定元がどう扱われるかにあります。

* **エラー**は、その設定元が**破棄された**ことを示します。その設定元からはルールが一切読み込まれません。
* **警告**は、その設定元は有効なままで、拒否された部分だけが無視されることを示します。

どちらの場合も `degraded` になります。

<Note>
  `cc-safety-net status` が出力する判定は `ready` と `degraded` の 2 つだけで、スナップショットの状態がそのまま反映されます。Claude Code のプラグインが無効でも判定は変わりません。その場合、`status` は `Not active` の先頭項目として次のように報告します。"plugin cc-safety-net\@cc-marketplace is disabled in Claude Code; nothing is enforced in Claude Code until it is re-enabled. Other integrations are not affected."
</Note>

## 無効な設定の扱い

設定が無効だというだけの理由で、通常の作業が拒否されることはありません。無効な設定は強制されませんが、それによってエージェントが何もできなくなることもありません。

* 検証できないルールの設定元は**破棄**され、そのルールは強制されなくなります。
* 検証に成功した他のスコープは、引き続きルールを強制します。
* 組み込みの保護は、どの場合でも適用されます。破壊的コマンドのルール、シークレット保護、ポリシーファイルの保護、Git メタデータの保護は、ルールの設定を読み取らないためです。
* ユーザーポリシーのファイルを読み取れない場合は**安全側の**既定値に戻るため、破壊的コマンドの保護とシークレット保護は有効なままです。プロジェクトポリシーのファイルを読み取れない場合は、そのファイルの内容が一切反映されず、ユーザーポリシーがそのまま有効です。

degraded の間に使う特別な復旧モードや許可リストはありません。設定できないことを理由に拒否される操作がないためです。`rule.json` の読み取りも、その場での編集も、`cc-safety-net rule update` の実行も通常のツール呼び出しであり、それぞれの内容に応じて成功または失敗します。そのため、エージェント自身が設定を修復できます。

<Warning>
  設定元が破棄されると、その設定元による拒否が**なくなります**。破棄された rulebook がブロックしていたコマンドは、修復するまで実行できます。エラーに名前が記載された rulebook は、保護を続けていません。
</Warning>

どの状態でも保護され続けるのは、両スコープの `policy.json` です。ポリシーファイルの保護と Git メタデータの保護は、ポリシースナップショットの読み込みより**前**に動作するため、設定が壊れていても影響を受けません。ブロックされる操作の詳細は[ポリシー](/docs/ja/configuration/policy)を参照してください。

## 設定のフォールバック一覧

### エラー：設定元が破棄される

| 失敗の内容 | 強制されなくなるもの | 維持されるもの |
| - | - | - |
| リモートの設定元がまだ取り込まれておらず、`rules/<name>/rulebook.json` がない | その rulebook 1 つだけ | その他すべての rulebook と組み込み保護 |
| ローカルの設定元の `rules/<name>/rulebook.json` がない、または削除された | その rulebook 1 つだけ | その他すべての rulebook と組み込み保護 |
| rulebook ファイルが有効な JSON でない、または rulebook のスキーマに適合しない | その rulebook 1 つだけ | その他すべての rulebook と組み込み保護 |
| rulebook の `name` が、それを列挙している設定元と一致しない | その rulebook 1 つだけ | その他すべての rulebook と組み込み保護 |
| `rule.json` が不正、空、または未対応の `version` | `transparent_wrappers` と `command_tools` も**含めた**そのスコープ全体 | 他スコープの検証済みルールと、すべての組み込み保護 |
| ポリシー用のファイルシステムを安全に読み取れない | そのスコープ | 他スコープの検証済みルールと、すべての組み込み保護 |

いずれのメッセージも、拒否したファイルまたは設定元と、それに応じた修復方法を示します。リモートの設定元の rulebook がない場合は ``run `cc-safety-net rule update` to vendor <source>`` で終わります。ローカルの設定元の rulebook がない場合は `create that file or remove that source from the rules config` で終わります。rulebook が無効な場合と名前が一致しない場合は、どちらも `fix that file` で終わります。

### 警告：設定元は有効なまま

| 失敗の内容 | 無視されるもの | 維持されるもの |
| - | - | - |
| 有効な rulebook 2 つが同じ名前を使っている | 後から読み込まれた rulebook。そのルールは無効になる | 先に名前を確保した側。ユーザースコープを先に解決する |
| `rule.json` に未知の override キーがある | その override 1 つだけ | その他の override とルールは設定どおり有効 |
| プロジェクトの override がユーザースコープのルールを対象にしている | その override 1 つだけ | 対象のルールはユーザー設定の状態を維持する |

<Note>
  rulebook はすべてライブファイルです。保存した編集は次のツール呼び出しから有効になり、反映のための操作は要りません。編集して壊した場合も、黙って見過ごされることはありません。パースできない、またはスキーマに適合しないファイルは、上記の `invalid rulebook` のエラーで破棄され、削除されたファイルは `missing rulebook file` のエラーで破棄されます。どちらの場合もスナップショットは `degraded` になります。
</Note>

rulebook の名前が重複した場合は、先に読み込んだ側を使います。ユーザースコープを先に読み込むため、同名のプロジェクト rulebook は読み込まれません。ルールの一部だけが隠れるわけではありません。この衝突は致命的エラーではなく、先に読み込んだ側を採用して解決されるため、一方のスコープでの変更が、他方のスコープがすでに確保している名前を理由に失敗することはありません。

### `policy.json`：救済するか、安全側の既定値に置き換える

| 状況 | 結果 | 状態 |
| - | - | - |
| ユーザーファイルがない | 組み込みの既定値 | `ready`。診断も出ない |
| ユーザーファイルが空、または空白のみ | 組み込みの安全側の既定値 | `degraded` |
| ユーザーファイルが有効な JSON ではない | 組み込みの安全側の既定値 | `degraded` |
| ユーザーファイルのパース結果がオブジェクトでない | 組み込みの安全側の既定値 | `degraded` |
| ユーザーファイルはオブジェクトにパースできるが検証に失敗 | **フィールド単位で救済**。認識できた有効なセクションは残し、それ以外を安全側の既定値に置き換える | `degraded` |
| ユーザーファイルが有効 | 記述したポリシーそのもの | `ready` |
| プロジェクトファイルがない | ユーザーポリシーのみ | `ready`。診断も出ない |
| プロジェクトファイルが空、有効な JSON ではない、またはパース結果がオブジェクトでない | ユーザーポリシーのみ。プロジェクトファイルは何も寄与しない | `degraded` |
| プロジェクトファイルはオブジェクトにパースできるが、一部のフィールドが検証に失敗 | フィールド単位で救済。認識できた有効なフィールドはユーザーポリシーの上に重なり、それ以外は破棄される | `degraded` |
| プロジェクトファイルに `audit` セクションがある | ユーザーポリシーの audit 設定。プロジェクトファイルの他のフィールドは重なったまま | `degraded` |
| ユーザーファイルを読み取れず、プロジェクトファイルがフィールドを設定している | 組み込みの安全側の既定値の上に、プロジェクトファイルの有効なフィールドが重なる | `degraded` |

フィールド単位で救済するため、1 つの無効なフィールドが、ファイル内の他の保護まで無効にすることはありません。安全側の既定値は、拒否を増やす設定です。破壊的コマンドの保護とシークレット保護を強制的に有効にし、両方の allow path にある無効な項目と、保護を無効にする override を破棄します。有効なシークレットの allow path は、救済後のポリシーにも残ります。`.cc-safety-net/policy.json` のプロジェクトファイルも同じように救済されますが、1 点だけ違いがあります。`audit` はユーザースコープ専用のため、プロジェクトファイルの `audit` セクションは `project policy audit settings are ignored; audit is user scope only` という診断とともに無視されます。フィールドごとの挙動は[ポリシー](/docs/ja/configuration/policy)を参照してください。

ランタイムが `policy.json` を書き換えることはありません。手作業で修復するか、ダッシュボードの修復機能を使ってください。

ファイルにエラーがある間、ダッシュボードのフォームには救済後の値ではなく既定値一式が表示され、修復するまで保存できません。修復機能は、認識できた有効な設定を残します。ファイル全体が既定値に置き換わるのは、JSON をパースできない場合だけです。

## `rule.json` で宣言する対象範囲

`transparent_wrappers` と `command_tools` の 2 つのフィールドは、独自のルールを追加するのではなく、組み込みの解析が届く範囲を広げます。どちらも rulebook ではなく `rule.json` で宣言しますが、`rule.json` にはダイジェストがありません。その結果、次の 2 点が生じます。

* **rulebook が破棄された場合**でも、どちらのフィールドも維持されます。`rule.json` 自体は読み取れるためです。
* **`rule.json` を読み取れない場合**は、そのスコープで両方とも失われます。フォールバックに使える検証済みのコピーがないためです。解析は、そのスコープの wrapper 越しに実行される保護対象コマンドを見つけられなくなり、そのスコープが宣言した[コミュニティ製のシェルツール](/docs/ja/configuration/custom-rules#community-shell-tools)は解析されない状態に戻ります。組み込みの 8 つの wrapper（`caffeinate`、`exec`、`nice`、`nohup`、`setsid`、`stdbuf`、`time`、`timeout`）はファイルを必要としないため影響を受けず、もう一方のスコープの宣言も引き続き適用されます。

拒否された設定が、独自のルールを失わせるだけでなく組み込みの対象範囲まで狭めてしまうのは、この 2 つのフィールドです。この理由でスコープが破棄された場合は、まず `rule.json` を修復してください。

## fail closed になるケース

「fail closed」は、実行時の失敗や解析の失敗に対して**その 1 回のツール呼び出し**を拒否することを指す言葉であり、設定が無効なときの動作を指す言葉ではありません。

| ケース | 動作 |
| - | - |
| いずれかのガードステージで、アナライザーまたは依存ライブラリが予期しない例外を投げる | どのモードでも、「failed closed」の理由を付けてツール呼び出しを拒否 |
| hook やツールのペイロードが不正、またはサイズ超過 | どのモードでも拒否 |
| コマンド判定に回されたコマンドが空、または空白のみ | どのモードでも拒否 |
| コマンドが再帰の深さ上限を超える | どのモードでも拒否 |
| コマンドの構造が安全に検証できる上限を超える | どのモードでも拒否 |
| `fail_closed` 機能が有効で、コマンドをトークン化できない | 拒否。[strict モード](/docs/ja/configuration/modes#strict-mode)を参照 |
| worktree の緩和で、linked worktree だと確実に判定できない | 緩和を適用せず、より厳しい既定値を維持 |

設定が無効な場合の動作は、これとは逆です。ルールの設定元を破棄し、`policy.json` を救済するか安全側の既定値に置き換えたうえで、作業は続行します。

## degraded 状態の報告

| 表示箇所 | 表示内容 |
| - | - |
| 次にユーザーの目に触れる拒否 | ブロックメッセージに、詳しい理由を含む `Config warning:` の行を追加 |
| 監査レコード | 許可・拒否の両方の判定に付く `configFallback` フラグ |
| `cc-safety-net status` | `ready` または `degraded` の判定と、`Not active` 内の診断 1 件につき 1 行 |
| `cc-safety-net doctor` | タイトルが "Runtime is enforcing a fallback configuration" の警告 `config.runtime-degraded`。詳細欄には理由の全文 |
| `cc-safety-net rule list` | `Issues` と `Warnings` のセクション。ルールの設定のみが対象 |
| ステータスライン | スナップショットが degraded の間に表示される `⚠️` |
| ダッシュボード | 保護状況のバナーに表示される状態 |

ルールの設定と `policy.json` の両方を報告するのは `doctor` だけです。各コマンドのオプションと終了時の挙動は[CLI コマンド](/docs/ja/reference/cli-commands)を参照してください。

構造上の制限が 2 つあります。

* `Config warning:` の行と監査ログの `configFallback` フラグが付くのは、スナップショットを読み込んだ**後**に行われた判定だけです。ポリシーファイルと Git メタデータによる拒否はそれより前に起きるため、どちらも含まれません。
* 診断は、拒否したファイルと条件の**名前**を示すだけで、ファイルの中身をそのまま写すことはありません。不正な設定ファイルに含まれるシークレットがメッセージに再出力されることはありません。

## 気づきやすい失敗と気づきにくい失敗

* **設定元が破棄されても、その場では通知されません。** 拒否が減るため、通常のセッションでは問題に気づけないことがあります。ルールの設定変更後とアップグレード後には、`cc-safety-net status` を実行してください。詳しい診断には `doctor` を使います。
* **未移行の旧設定は、さらに見つけにくい問題です。** ランタイムはそのファイルを読み込まず、`status` も何も報告しません。そのため、旧設定のルールが何も保護していない状態でも、スナップショットは `ready` のままです。`doctor` は `warning` 重大度の finding `config.legacy-ignored` として報告し、`rule verify` も検出します。
* **無効な `policy.json` は、たいてい自分から気づけます。** 拒否されたセクションは、2 つの保護を有効にし、allow path と保護を無効化する override を破棄する安全側の既定値に戻るため、設定したつもりより*多く*の拒否が発生するからです。
* **無効な `policy.json` の、気づきにくい側面：**無効な `safety.level` は黙って `standard` に戻るため、`paranoid` の綴り間違いは preset を**引き下げて**しまいます。無効な `secret_protection.deny_paths` の項目や、ルールを既定より強くするルール単位の override も、修復されずに破棄されます。
* 常時表示されるサインは、ステータスラインの表示だけです。`Config warning:` の行は無関係な拒否が起きたときにしか現れず、その他の表示箇所は、コマンドを実行するかダッシュボードを開くまで何も知らせません。

## 設定を復旧する

以下のコマンドはいずれも通常のツール呼び出しなので、ランタイムが degraded の間でも、エージェント自身が一連の手順をすべて実行できます。各コマンドのオプションと終了時の挙動は[CLI コマンド](/docs/ja/reference/cli-commands)にあります。

<Steps>
  <Step title="判定を確認する">
    ```bash theme={"dark"}
    npx cc-safety-net status
    ```

    `ready` または `degraded` の判定と、`Not active` 内の診断を 1 件ずつ表示します。Claude Code のプラグインが無効な場合は、別の判定にはなりません。`Not active` の先頭項目として表示されます。終了コードを使うゲートにはせず、日常の状態確認に使ってください。
  </Step>

  <Step title="詳細なレポートを取得する">
    ```bash theme={"dark"}
    npx cc-safety-net doctor
    ```

    ルールの設定と `policy.json` の両方を対象にする唯一のコマンドです。ランタイムが degraded の場合は `config.runtime-degraded` の警告として表示され、その詳細欄に、拒否されたすべての設定元を含む理由の全文が出ます。
  </Step>

  <Step title="実際に有効なものを確認する">
    ```bash theme={"dark"}
    npx cc-safety-net rule list
    ```

    実際に有効になっているものを一覧表示し、続けて `Issues` と `Warnings` を表示します。破棄された設定元と一緒に失われたルールを確認するときに使います。終了コードが 0 以外になるのは、設定にエラーがある場合だけです。警告だけの場合は `Warnings` に出力したうえで `0` を返します。
  </Step>

  <Step title="ルールの設定を検証する">
    ```bash theme={"dark"}
    npx cc-safety-net rule verify
    ```

    ユーザーとプロジェクトの `rule.json` をスキーマに照らして検証し、実行時と同じ読み込みを再現するため、ガードが遭遇するのと同じ問題を検出できます。移行が必要な旧形式のファイルも検出します。問題がなければ `All configs valid.` または `Configs valid with warnings.` を出力し、問題があれば `Config validation failed.` を出力して終了コード `1` を返します。書き込みが 1 つだけ発生する場合があります。有効な `rule.json` に `$schema` キーがない場合は追加し、`Added $schema to <scope> config.` と出力します。それ以外の変更は行いません。
  </Step>

  <Step title="設定元を修復する">
    ローカルの rulebook にコマンドは不要です。診断が指すファイルを編集すれば、次のツール呼び出しでガードがそれを読み込みます。

    リモートの設定元がない、または古い場合は、取り込み直します。

    ```bash theme={"dark"}
    npx cc-safety-net rule update
    ```

    設定済みのリモートの設定元をすべて解決し直して `rules/<name>/rulebook.json` に書き出し、そのうえでガードと同じ方法でそのスコープを読み込み直します。設定元を 1 つ指定すればそれだけを更新でき、ユーザースコープには `--global` を付けます。診断が残っている場合は成功と報告せず、診断を出力して 0 以外の終了コードを返します。`Rule config updated.` に続いて `Active rulebooks (<n>):` の一覧が出れば、そのスコープに問題はありません。

    更新は設定元ごとに独立しています。失敗した設定元は `Failed to update <spec>: <message>` を出力し、すでにあるコピーをそのまま保持します。他の設定元は更新されます。検証の対象は、更新しているスコープだけです。
  </Step>

  <Step title="policy.json を手作業で直す">
    ランタイムが `policy.json` を書き換えることはありません。診断に挙がったフィールドを自分で修正するか、ダッシュボードの修復機能を使ったうえで、`status` を実行し直してください。スキーマ全体と既定値は[ポリシー](/docs/ja/configuration/policy)を参照してください。
  </Step>
</Steps>

修復のたびに `status` を実行し直してください。ランタイムは次のツール呼び出しで再読み込みするため、何かを再起動する必要はありません。

## 以前のバージョンのロックとキャッシュを移行する

以前のバージョンで設定したスコープには、`rule.lock` と `cache` ディレクトリが残っていることがあります。どちらも読み込まれなくなったため、スナップショットは `ready` のままで、そこから強制されるものもありません。`cc-safety-net doctor` は、これらを `info` 重大度の finding `config.v2-leftovers`（タイトルは "Rulebook lock and cache leftovers detected"）として報告し、詳細欄に `Files an earlier version left behind are no longer read: <paths>.` を出します。修正のヒントは ``Run `cc-safety-net rule sync` (add `--global` for user scope) to migrate them, then rerun doctor.`` です。

現在の `rule sync` が行うのは、この移行だけです。オフラインで動作し、最初に非推奨の告知を出力します。

```
`cc-safety-net rule sync` is deprecated: rulebooks are live files that need no synchronization. This run only migrates the lock and cache an earlier version left behind.
```

記録されたダイジェストと一致するキャッシュ済み rulebook を取り込んだうえで、ロックとキャッシュディレクトリを削除します。これらのファイルが残っているのにそのスコープの `rule.json` がない、または読み取れない場合は、実行を中止します。設定元を記録しているのがロックだけになるためです。出力されるメッセージの全体は [`rule sync`](/docs/ja/reference/cli-commands#rule-sync) を参照してください。

## 旧形式のインラインルールを移行する

旧形式のインライン設定ファイル（`~/.cc-safety-net/config.json` と `.safety-net.json`）は、実行時に読み込まれません。他の部分は動作しますが、**それらのルールはまったく強制されず**、スナップショットは `ready` のままです。ランタイムも `status` もこの問題を報告しないため、アップグレード後には、この状態を見落とすことがあります。`cc-safety-net doctor` は、見つけたファイルを `warning` 重大度の finding `config.legacy-ignored`（タイトルは `Legacy inline rule configs are ignored`）として報告し、`rule migrate` の実行を促します。この警告は `doctor` の終了コードに影響しません。移行待ちの旧形式ファイルは、`cc-safety-net rule verify` でも検出できます。

変換したい旧設定があるプロジェクトで、移行コマンドを実行します。

```bash theme={"dark"}
npx -y cc-safety-net rule migrate
```

`rule migrate` は同期の結果をそのまま引き継ぎます。移行後のスコープに診断が残っている場合は、成功とは報告せず、その診断を出力します。移行後のファイルは書き込まれ、旧形式のファイルも残るため、報告された問題を直してから再実行できます。移行先となる rulebook の構成は[カスタムルール](/docs/ja/configuration/custom-rules)を参照してください。

## 関連ページ

<CardGroup cols={2}>
  <Card title="ポリシー" icon="file-lock" href="/docs/ja/configuration/policy">
    `policy.json` の完全な仕様、既定値、フィールド単位の救済。
  </Card>

  <Card title="カスタムルール" icon="list-checks" href="/docs/ja/configuration/custom-rules">
    rulebook の構成、設定元、取り込み、override、transparent wrapper。
  </Card>

  <Card title="CLI コマンド" icon="terminal" href="/docs/ja/reference/cli-commands">
    `status`、`doctor`、および各 `rule` サブコマンドのオプションと終了時の挙動。
  </Card>

  <Card title="監査ログ" icon="scroll-text" href="/docs/ja/reference/audit-log">
    判定が記録される場所、エントリのスキーマ、保持期間。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.