親エージェントは、これらのシグナルを使用して影響を受けるコードを特定し、必要に応じてリファクタリングします。

### 事前インストールモード（Bash フック）

`.claude/settings.json` に `PreToolUse:Bash` フックを設定して、
パッケージマネージャーのインストールコマンドの事前監査を有効にします。これは
インターセプトモードを補完するものであり（置き換えるものではありません）— 両者を組み合わせることで多層的な防御を構成します。

1. Claude が Bash ツール呼び出しを試みます（例: `npm install [email protected]`）
2. `PreToolUse` フックは呼び出しが実行される前に発火し、
   `safer-dependencies-pretooluse-bash.sh` を呼び出します
3. 純粋な bash の初期フィルターが、パッケージマネージャー以外のコマンドを約115ミリ秒で短絡します
   （Python を起動しません）。そのため、`git status` / `ls` / `npm test` は
   ホットパス上で無視できるほどのコストしかかかりません
4. 認識されたパッケージマネージャーのインストール（`npm`/`pnpm`/`yarn` の
   `install`/`i`/`add`）に対して、ヘルパーは `shlex` でトークン化し、各
   `pkg@version` 引数を抽出して OSV に POST します
5. 脆弱性のある具象ピンが見つかった場合、フックは
   `permissionDecision: "deny"` を返します。各検出結果には GHSA-ID + CVSS +
   サマリーに加え、safer-dependencies スキルを呼び出すためのヒントが含まれます
6. インストールは実行されません — ネットワーク取得も postinstall スクリプトもありません

**なぜインターセプトモードに加えてこれが存在するのか:** post-write シム
は Bash を認識できません。`npm install [email protected]` は、監査が発火する前に
完了まで実行され（postinstall スクリプトも実行されます）。`npm install -g
typosquat-pkg` はプロジェクトマニフェストを一切書き込みません。事前インストールモード
は、これらのギャップを構造的に埋めます。

事前インストールモードは、ユーザーが**入力した**もの（コマンドライン上の
`pkg@version` 引数）しか認識できません。リゾルバーが実際にインストールする推移的依存ツリーは見えません。
**インストール後モード**（後述）は、インストール完了後にロックファイルを監査します — この2つのモードは補完的であり、冗長ではありません。

**対象範囲:** ここでカバーされるパッケージマネージャー CLI は、5つのエコシステムにわたります
（npm/pnpm/yarn/bun/npx/deno、pip/pip3/pipx/pipenv/uv/uvx/poetry、gem/bundle、
go、cargo）。さらに、インターセプトモード経由で Maven も対象です（Maven の依存関係は通常
`pom.xml`/`build.gradle` に宣言され、CLI 動詞で追加されることはありません）。

> **既知のギャップ:** Maven CLI は、以下による直接ダウンロードをサポートしています
> `mvn dependency:get -Dartifact=group:art:version` および `mvn dependency:copy`。
> このフックはまだこれらの呼び出しを認識しません。これらを
> 定期的に使用する場合、既存の post-write シムはマニフェストに書き込まれたものを
> 引き続き検出しますが、取得前保護は上記の
> エコシステムにのみ適用されます。フォローアップとして追跡されています。

認識されるエコシステム別の構文:

| PM | Verbs | Concrete-pin syntax |
|---|---|---|
| `npm`, `pnpm`, `yarn`, `bun` | `install`, `i`, `add`（`yarn`/`pnpm dlx`、`bun x`、`yarn create` も含む） | `[email protected]`, `@scope/[email protected]` |
| `npx` | （動詞なし — パッケージが最初の位置引数） | `[email protected]` |
| `deno` | `add`, `install` | `npm:[email protected]`（npm プレフィックス付きスペック） |
| `pip`, `pip3`, `pipx`, `pipenv`, `uv`, `uvx`, `poetry` | `install`（pip/pip3/pipx/pipenv）/ `add`（uv/poetry）/ 動詞なし（uvx） | `pkg==1.2.3`（extras の `pkg[extra]==X` も処理されます） |
| `gem`, `bundle` | `install` (gem) / `add` | `-v 1.2.3`, `--version 1.2.3`, `--version=1.2.3`（別フラグ） |
| `go` | `get`, `install` | `[email protected]`（Go モジュールの規則により `v` プレフィックスを含める必要があります） |
| `cargo` | `add`, `install` | `[email protected]` |

範囲ピン（npm の `^4.17`、pip の `>=`、poetry の `^`/`~`、Go の `@latest`）および
未指定バージョンは、インストール後にインターセプトモードへ渡されます —
post-write シムがリゾルバーの選択結果を監査します。安全なバージョンへの
自動書き換えはフォローアップとして予定されています。

**障害モード:** フェイルオープン。あらゆるエラー（Python の欠如、ネットワークの瞬断、
不正な入力）は出力なしで終了コード 0 を返し、bash の実行を継続させます。
インストール後もインターセプトモードが実行されるため、事前チェックの失敗は
既存の保護にグレースフルにフォールバックします。

**拒否の例:**```
safer-dependencies pre-flight audit blocked this install.
Vulnerable pinned version(s) detected:
  - [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash
Re-run with a patched version, or invoke the safer-dependencies skill
for a recommended pin.

### Post-Agentモード（エージェントフックペア）

上記の4つのモードは、**ルートセッション**のツール呼び出しでのみ発動します。ルートセッションがサブエージェントを（`Agent` ツール経由で、多くのスキルやスラッシュコマンドが内部でこれを行います）ディスパッチすると、サブエージェントのWrite/Edit/Bash呼び出しはこれらすべてをバイパスします。Post-Agentモードは、そのギャップに対するリアクティブなセーフティネットです。

1. `PreToolUse:Agent` フック（`safer-dependencies-pretooluse-agent.sh`）は、各Agentディスパッチの直前に実行され、`/tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel` のセンチネルファイルをタッチします（セッションIDがない場合はPPIDのみの名前にフォールバックします）。
2. サブエージェントが実行され、マニフェストやロックファイルを書き込むことがあります。
3. `PostToolUse:Agent` フック（`safer-dependencies-posttooluse-agent.sh`）は、Agent呼び出しが戻った後に実行され、センチネルより新しいすべてのマニフェストとロックファイルを `find` し、同じシムパスを介してそれぞれを監査します。
4. 検出結果は `additionalContext` としてルートセッションの次のターンに表示されます。センチネルは削除されます。

ネストされたサブエージェントは自動的にカバーされます。ルートの `PostToolUse:Agent` は、外側のエージェントのすべての作業（*それ*がディスパッチしたものを含む）がディスクに書き込まれた後にのみ発動します。唯一のギャップは、マニフェストやロックファイルを書き込まないグローバルインストール（`npm install -g …`）です。スキャンするものがありません。他のフックと同様に、フェイルオープンです。エラー（センチネル欠落、シム欠落、ペイロード読み取り不能）はすべて静かに終了コード0で抜けます。設計根拠の全容は `skills/safer-dependencies.md` にあります。

## 発動条件

このスキルは、Claudeが以下を行う場合に自動的に発動します:

**マニフェスト / インストール操作**
- `package.json`、`requirements.txt`、`Gemfile`、`pom.xml`、`build.gradle`、`Cargo.toml`、`go.mod`、またはその他のサポート対象マニフェストでパッケージを追加・更新する
- マニフェストでまだ宣言されていないパッケージの `import`、`require`、`use` を記述する
- ロックファイルを生成または更新する（新規・変更エントリのみチェック）
- Bashでパッケージマネージャのインストールを実行する（`npm install`、`bundle install`、`poetry install`、`uv sync`、`go mod tidy` など）— Pre-Installはコマンド引数を監査し、Post-Installは生成されたロックファイルを監査します
- 固定されたパッケージマネージャのインストール手順を埋め込んだ `Dockerfile` やCIワークフロー（`.github/workflows/*.yml` など）を記述する

**選択・推奨の質問**
- ライブラリ/フレームワークの比較: "axiosを使うべきかnode-fetchを使うべきか？"、"moment vs dayjs?"、"XとYはどちらが良いか？"
- 推奨リクエスト: "Python用の良いHTTPクライアントは？"、"Go用のロギングライブラリを勧めて"、"NodeでCSVを扱うパッケージは？"
- バージョン選択: "Djangoのどのバージョンを使うべきか？"、"最新の安定版Flaskは？"

**使用意図の表明（追加前）**
- "これにFastAPIを使いたい"、"Celeryを追加しようと考えている"、"ORMとしてPrismaを検討している"、"Tailwindを使おう"

**パッケージの健全性・信頼性の質問**
- "moment.jsはまだメンテナンスされているか？"、"このgemはまだアクティブか？"、"Xは放棄されたか？"、"XはEOLか？"、"このパッケージを信頼できるか？"、"fakerが最後に更新されたのはいつか？"

**スキャフォールディングコマンド**
- `npx create-react-app`、`npm create vite@latest`、`django-admin startproject`、`rails new`、`cargo new` + `cargo add`、"新しいFastAPIプロジェクトを立ち上げる"

**暗黙のパッケージ追加（新しい依存関係を暗示する機能リクエスト）**
- "アプリにRedisキャッシュを追加する"、"Postgresに接続する"、"JWT認証を追加する"、"メールを送信するコードを書く" — その機能に対応するパッケージがまだマニフェストにない場合に発動します

**移行・移植**
- "requestsからhttpxに移行する"、"CRAからViteに移行する"、"momentからdate-fnsに移植する" — 受け入れるパッケージを監査します

次の場合には**発動しません**:

- 標準ライブラリのインポート（`os`、`fs`、`java.util.*` など）
- 変更されていない、既に宣言済みの依存関係
- パッケージが内部でどのように動作するかについての学術的な議論（"Reactのレコンサイラーを説明して"、"webpackのモジュール解決はどのように動作するのか？"）— 比較・選択の質問では発動します
- OSレベルのアプリ、ランタイム、IDE拡張機能のインストール（Python自体、Docker、Homebrew、VS Code拡張機能）

## このリポジトリの内容

これは**スキル+フックバンドル**であり、単一のスキルファイルではありません。完全なインストールでは以下の部品を配置します:

| File | Role |
|---|---|
| `skills/safer-dependencies.md` | **スキル**（`SKILL.md` インストール後）。監査手順を説明し、インストール/統計用の管理モードを含みます。 |
| `skills/safer-dependencies-shim.sh` | `PostToolUse:Write`/`Edit` フック — マニフェスト+ロックファイルの書き込みを監査し、脆弱なバージョンをその場で自動修正します（Intercept Mode）。 |
| `skills/safer-dependencies-pretooluse-bash.sh` | `PreToolUse:Bash` フック — パッケージマネージャのインストールコマンドの事前OSV監査。インストール実行前に脆弱なバージョン固定（pin）を拒否します（Pre-Install Mode）。 |
| `skills/safer-dependencies-posttooluse-bash.sh` | `PostToolUse:Bash` フック — Bashコマンド実行後の事後監査。新しく書き込まれたロックファイル、`sed`/`jq`/スクリプトで編集されたマニフェスト、および素の`pip install`の解決済み環境における推移的CVEを検出します（Post-Install Mode）。 |
| `skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh` | `PreToolUse:Agent` + `PostToolUse:Agent` フックペア — サブエージェントのカバレッジギャップを埋めます。モード2–4はルートセッションのツール呼び出しでのみ発動するため、サブエージェントが書き込んだマニフェストはこれらをバイパスします。Post-Agentは各Agentツール呼び出しが戻った後にサブエージェントが書き込んだ内容を監査します（Post-Agent Mode）。 |
| `skills/scripts/` | 全フックで使用される共有Pythonライブラリ（`safedep/`）とスタンドアロンのリゾルバスクリプト。 |
| `skills/scripts/safer_dependencies_manager.py` | 対話型インストール、使用統計、セットアップ検証のための管理モジュール。 |

スキルファイルだけでは不十分です。フックがなければ、自動呼び出しはClaudeがスキルを使おうと判断するかどうかに依存します。完全なカバレッジのためには5つの部品すべてをインストールしてください。多くのスキルやスラッシュコマンドは内部でサブエージェントをディスパッチするため、明示的にサブエージェントを生成しなくてもPost-Agentペアは重要です。（スキル単体ではカバレッジを保証できない理由については、[FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md#why-a-skill-alone-is-not-sufficient) を参照してください。）

## サポート対象エコシステム

| エコシステム | マニフェスト | ロックファイル |
|-----------|----------|-----------|
| npm | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| PyPI | `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, `setup.cfg` | `Pipfile.lock`, `poetry.lock`, `uv.lock` |
| RubyGems | `Gemfile`, `*.gemspec` | `Gemfile.lock` |
| Maven | `pom.xml`, `build.gradle`, `libs.versions.toml` | -- |
| Go | `go.mod` | `go.sum` |
| Rust | `Cargo.toml` | `Cargo.lock` |
| PHP (Composer) | `composer.json` | `composer.lock` |

## インストール

このプロジェクトが初めてですか？ **[GETTING-STARTED.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/GETTING-STARTED.md)** から始めてください。簡単な手順は次のとおりです:```bash
git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies
python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

分析を容易にするには、ログを手動で解析する代わりに、Claudeに使用統計を尋ねてください:```
"Show safer-dependencies stats for the last month"

プリインストールモードの例 (Bashフック、脆弱なピンは拒否):```json
{
  "ts": "2026-04-23T06:56:21Z",
  "schema": "2.2",
  "source": {
    "component": "bash.pretooluse",
    "script": "pretooluse-bash.sh",
    "hook": "PreToolUse:Bash",
    "tool": "Bash",
    "mode": "intercept",
    "model": "claude-sonnet-4-6"
  },
  "file": "bash:npm install [email protected] [email protected]",
  "ecosystem": "npm",
  "checked": ["[email protected]", "[email protected]"],
  "findings": [
    "BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
  ],
  "abandoned": [],
  "stale": [],
  "typosquat": [],
  "unknown": [],
  "signatures": [],
  "notes": [],
  "clean": ["[email protected]"]
}

フェイルオープンのエントリは、「前提となる何かが欠けていたため、このフックは起動したものの監査を行わずに早期終了した」ことを示します。上記の jq フィルター (`select(.source.mode == "fail_open")`) を使用して、ログ内のサイレントな保護喪失イベントをすべて浮き彫りにしてください。

シムがドライラン モード (`SAFE_DEP_DRY_RUN=1`) で実行されると、エントリには `"mode": "dry_run"` も含まれるため、事後分析で監査専用の呼び出しをフィルタリングできます。

## 要件

- Python 3.9+ (フックはこれを検査し、古いインタープリターではフェイルオープンします)
- `curl` (レジストリ API 呼び出しと OSV 脆弱性チェック用)
- エコシステムツール (任意。欠けている場合、スキルは OSV API にフォールバックします):
  - `npm` (npm パッケージ用)
  - `pip-audit` (Python パッケージ用)
  - `bundle` (Ruby パッケージ用)
  - `dependency-check` (Java パッケージ用)

## FAQ

設計判断の根拠 (`PreToolUse` ではなく `PostToolUse` を選んだ理由、署名を検証しない理由、スクリプトとシムを重複させている理由、スキル読み込みの落とし穴など) は [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md) に文書化されています。