Claude Code Mods入門｜Hooksとの3つの違いと安全な導入手順

結論: Claude Code Modsは、イベントの観測に加えて、プロンプトやツール呼び出しの書き換え、UIの追加、組み込み機能の置き換えまで扱える拡張機構です。便利さと同じだけ権限も広く、Modが起動する処理はClaude CodeのBashサンドボックス外で動きます。第三者Modは、配布元、コード、利用権限を確認し、テスト環境の1セッションから試してください。

この記事の要点:

• Modsは2026年10月1日に発表され、ターミナル版ではClaude Code v2.1.287以降で既定有効です
• Settings Hooksとの主な差は、イベントの書き換え、UI描画、通常処理の代行まで扱えることです
• Modは利用者と同じ権限を持ち、ファイル、環境変数、設定、プロンプト、ツール呼び出し、モデル利用量へ到達できます

対象読者: Claude CodeのHooksやプラグインを使っており、独自UIや実行制御を追加したい開発者。第三者Modを組織へ配布する前に、審査と切り戻しの基準を作りたい管理者。

この記事で持ち帰れるもの: Modsの選択条件、最小構成、実行前監査、個人試行から組織導入までの順序です。

根拠は、2026年10月8日に確認したAnthropicの発表、公式ドキュメント、公式GitHubのv2.1.287リリースです。第三者Modの実機検証は対象外としました。Mods APIは変わり得るため、手元のバージョンが生成する型定義も確認してください。従来のイベント自動化は、Claude Code Hooks入門で整理しています。

導入前に見る順番を固定した図です。機能の魅力より先に、配布元、コード、権限を確認し、小さく試します。

実行前の確認順は、配布元→コード→権限→小規模試行です。機能の魅力より先に権限を確認します。

ModsはClaude Codeの動作へ入る拡張機構

ModsはClaude Codeの動き方や見え方を変えるJavaScript／TypeScript関数です。対象は、プロンプト送信、ツール呼び出し、権限確認、ターン、画面描画などのイベント。公式GitHubではv2.1.287の追加機能として記録されました。ターミナルでは最初に版を確認します。

claude --version

2.1.286以前なら更新してください。Desktop appは内蔵Claude Code v2.1.286以降、以降の手順はターミナル版v2.1.287以降が対象です。

プラグインとして配布するMod

ModはClaude Codeプラグインに組み込んで配布する機能で、最小構成は次の3ファイルです。

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

plugin.jsonは名前と版、hooks.jsonはモジュール、register.jsは対象イベントと処理を担います。配布には既存のplugin marketplaceと更新ポリシーを利用できます。

読み込み順でつながるイベントチェーン

複数のModは読み込み順にイベントを受け、next(e)で次へ渡す仕組みです。戻り値は逆順なので、先頭のModが入力を最初に、結果を最後に確認できます。組織配布では読み込み順も管理対象に含めてください。

観測・書き換え・代行の3動作

Modのイベント処理は、次の3種類です。

最初の自作Modは観測だけに絞ります。書き換えや代行では、Claude Code本体、別のMod、Hooksとの順序も検証対象です。

Hooksから広がった3つの操作領域

Settings Hooksはイベントからシェル、HTTP、prompt hook、agent hookを起動する仕組みで、単純なブロック、通知、監査ログに向きます。Modsはセッション内の関数として状態を持ち、ツール呼び出し、プロンプト、コマンド、ターン、UI描画を変更できます。

単純なブロックや通知にはHooksが適任です。セッション内のUIや処理自体を変える場合の候補がModsです。

選択基準は、Claude Code内部をどこまで変える必要があるかです。

違い1：イベント内容の書き換え

Settings HooksはPreToolUseでツールの許可・拒否や引数更新を扱います。一方、Modsの関数チェーンは、プロンプト、ツール呼び出し、コマンド、ターンの入力と結果までが対象です。秘密情報のマスクや安全な代替、条件付き再試行に使い、書き換え後は管理対象Hooksで再検査できます。

違い2：ターミナルとDesktopの独自UI

Modsはui.renderイベントへ入り、画面の行、ペイン、ボタン、入力欄を追加できます。Anthropicが公開している例は、コンテキスト使用率を示す「Token Weather」、危険コマンドの影響範囲を出す「Blast Radius」、編集履歴を順に確認する「Replay Theater」です。

描画の対応範囲には差があります。独自UIを表示できるのはターミナルとDesktop appです。VS Code拡張のチャットパネル、claude -p、Agent SDK、cloud sessionではhookだけが動くため、画面依存のModにはテキストへ戻す処理を用意します。

違い3：通常処理や組み込み機能の代行

Modはnext()を呼ばずに答えを返し、Claude Code本体の通常処理を置き換えられます。公式発表で示された例は、組み込み/diffのMod化と、無効化・独自実装への交換です。

置き換えは障害原因も増やします。初回は表示補助や観測に絞り、認証、権限、保存処理の代行は後へ回します。

Claude Code本体と同じ範囲に及ぶMod権限

Modsの最重要事項は、OS権限上の隔離がないことです。公式ドキュメントは「Mods aren't sandboxed」と明記しています。Claude CodeのBash sandboxingを有効にしても、Modが$.processで起動したプロセスはその外側で動きます。

実装APIの制限とセキュリティ境界の区別

ModはNode.jsやDOMへ直接触れず、ファイル、プロセス、HTTP、環境変数、設定、モデル、UIをMods APIの$経由で操作します。validateはこの呼び出しを列挙できます。ただし$には読み書き、プログラム起動、通信も含まれ、OS権限を隔離する境界ではありません。

対象に含まれる秘密情報・会話・利用量

公式ドキュメントが挙げる到達範囲には、次が含まれます。

• 環境変数と設定ファイルにあるAPIキー
• 送信したすべてのプロンプトと、Claudeが実行するツール呼び出し
• プロンプトやツール呼び出しの書き換え、別セッションへのメッセージ
• 利用者のプランまたはAPIキーを使ったモデル呼び出し
• 権限確認が表示される前のツール許可・拒否

表示用Modでも別のAPIを呼べます。説明文だけで判断せず、コードとvalidate結果を照合します。

sec-defaultの保護範囲

Team・Enterpriseでサインインした端末、またはmanaged settingsを持つ端末では、組み込みModのsec-defaultがユーザーModより先に読み込まれます。保護対象は、denyルール、managed hooks、system prompt、managed instructions、管理対象MCPです。

ただし、sec-defaultはMod全体のサンドボックスではありません。管理対象外のファイル操作、プロセス、通信、プロンプト変更は止めず、通常のRead(.env) denyルールもMod自身の$.fs.readには適用外です。組織では読み込むMod自体を制限します。

1セッションで試す最小構成

公式Docsの最小例に沿い、ツール呼び出し数を表示する観測専用Modを示します。この記事では実行していないため、v2.1.287以降でvalidateとテストを行ってください。

1. マニフェストと読み込み先の作成

.claude-plugin/plugin.jsonを作ります。

{
  "name": "tool-counter",
  "version": "0.1.0",
  "description": "Show the tool call count in the spinner."
}

次にhooks/hooks.jsonでモジュールを1つ指定します。

{
  "modules": ["./register.js"]
}

2. 観測と表示だけの登録

hooks/register.jsには、ツール呼び出しを数えるhookとspinnerを描くhookを登録します。

let calls = 0;

export function register(on) {
  on("tool.call", async ($, event, next) => {
    calls += 1;
    $.ui.invalidate("ui.render");
    return next(event);
  });

  on("ui.render", { component: "Spinner" }, async ($, event, next) => {
    return next({
      ...event,
      props: { ...event.props, suffix: ` · tool calls: ${calls}` },
    });
  });
}

この例はツールを拒否せず、引数を維持したままnext(event)へ渡し、表示用の数だけを更新します。

3. 実行前の静的検査

次のコマンドで構造、hook対象、Mods API呼び出しを列挙します。

claude plugin validate ./tool-counter

想定外の$.fs、$.process、$.http、$.env、$.modelがあればコードを確認します。Validation passedは安全性の証明ではありません。

4. テスト用ディレクトリでの一時読み込み

インストール前の読み込みは、テスト用リポジトリの1セッションに限定してください。

claude --plugin-dir ./tool-counter

/pluginでtool-counterの読み込みを確かめ、意図しない動きがあればセッションを終了してください。claude --safe-modeの停止対象は、ユーザーがインストールしたModと他のカスタマイズです。組み込みModは動き続けるため、「すべてのModなし」でも「Modだけを外した」比較でもありません。

5. 更新条件に含める自動テスト

claude plugin testでは、stub化したイベント入力に対する表示、拒否、書き換えを検証できます。

claude plugin test ./tool-counter

更新時は.claude-plugin/types/の型差分、validate、test、1セッション試行を一組で行います。

第三者Modの実行前審査7項目

DirectoryやmarketplaceのModもPC上で動くコードです。パッケージと同様にリポジトリと作者を確認します。

Directory掲載だけで導入判断は完了しません。試行へ進む条件は、配布元、実コード、必要権限を確認できることです。

実行前チェックリストは次の7項目です。

validateとコードの照合対象は、プロセスの引数、HTTP宛先、環境変数名、モデルへ送る内容です。Directory掲載だけでは安全性を保証しません。配布元、コードレビュー、組織ポリシーを別々に審査してください。

組織導入で決める4段階の許可範囲

全員へ配る前に、許可するModと配布経路を段階的に決めます。

段階1：ユーザーModの読み込み停止

allowManagedModsOnlyを有効にすると、利用者が持ち込むModのhookを止められます。プラグインのskills、commands、agents、MCP serversは残ります。

段階2：承認済みmarketplace限定

marketplaceのallowlistとdisableSideloadFlagsで、--plugin-dirや--plugin-urlによる持ち込みを抑えます。更新版を自動反映するか、tagやcommitで固定するかも決めます。

段階3：組織Modの管理配布

組織Modは管理者だけが書ける絶対パスのmarketplaceに置き、managed enabledPluginsで有効化します。GitHubなどからキャッシュへコピーしたプラグインは、管理設定で有効にしてもユーザーMod扱いです。

段階4：先頭に置く監査用Mod

ユーザーModも許可する場合は、policy ModをprependPluginsへ置けば、plugin.registerでAPI呼び出しを確認できます。この設定は既定リストを置き換えるため、sec-default@builtinの明示が必要です。

disableAllHooksの停止対象にはmanaged hooks、status line、/goalも含まれます。緊急停止と恒久ポリシーを分けてください。

【要注意】導入時に起きやすい5つの失敗

よくある質問

Q. ModsはHooksの後継で、置き換えが必要ですか

Hooksは引き続き利用できます。ブロック、ログ、通知、HTTP連携はHooks、UI描画、持続状態、広い書き換えはModsが候補です。

Q. TypeScriptで書く必要がありますか

JavaScriptとTypeScriptの両方を使えます。チームでは生成された型定義とテストを組み合わせると変更を追いやすくなります。

Q. Claude CodeにMod自体を書かせても安全ですか

Claude Codeが生成したModも第三者コードと同じ基準で審査し、validate、コードレビュー、テスト、切り戻しを行います。

Q. sec-defaultがあれば第三者Modを自由に入れられますか

sec-defaultはmanaged deny rulesやmanaged hooksを守りますが、許可済みModのファイル、プロセス、通信を隔離しません。配布元とModを組織側で絞ります。

Q. 問題が起きたとき、最初に何を確認しますか

まず/pluginでactive mod、版、読み込み順、debug logを確認してください。claude --safe-modeはユーザーがインストールしたModと他のカスタマイズを止める一方、組み込みModは対象外です。この条件差を踏まえて再現し、該当Modを個別にdisableして確かめます。

最初の1本に適した観測専用Mod

Modsはイベントの書き換え、UI描画、通常処理の代行まで扱う機構です。この強さは、秘密情報、端末操作、モデル利用量のリスクにも直結します。

まず版を確認し、観測専用Modを--plugin-dirで1セッションだけ試してください。組織展開では、配布元、コードレビュー、managed settings、切り戻し担当を一組で決める必要があります。

指示の再利用だけなら、実行コードを持つModsよりSKILL.mdが管理に向く選択肢です。Agent Skillsの設計ルールと、端末側の常設設定を整理するCLAUDE.mdの書き方も比較材料にしてください。

参考・出典

• Customize Claude Code with mods（<https://claude.com/resources/articles/claude-code-mods>）— Claude by Anthropic（参照日: 2026-10-08）
• Getting started with Claude Code mods（<https://claude.dev/blog/getting-started-with-claude-code-mods/>）— claude.dev（参照日: 2026-10-08）
• Mods overview（<https://code.claude.com/docs/en/plugins/mods/overview>）— Claude Code Docs（参照日: 2026-10-08）
• Manage mods for your organization（<https://code.claude.com/docs/en/plugins/mods/admin>）— Claude Code Docs（参照日: 2026-10-08）
• Claude Code v2.1.287 release（<https://github.com/anthropics/claude-code/releases/tag/v2.1.287>）— GitHub / Anthropic（参照日: 2026-10-08）
• Hooks reference（<https://code.claude.com/docs/en/hooks>）— Claude Code Docs（参照日: 2026-10-08）