Claude Code の mods — イベントフックで動きと見た目を変える
Anthropic は 2026年10月1日に、Claude Code の mods を公開しました。公式 changelog の 2.1.287（2026年10月1日）にも、「Added Claude Mods: plugins may now modify deeper behavior」と追加が記されています（Changelog、発表）。
mods は、プラグインの中に入る JavaScript または TypeScript のイベントハンドラです。Claude Code は、ツール呼び出し、送信されたプロンプト、画面の一部を描くときなどにハンドラを呼びます。ハンドラは、その出来事を見ることも、変えることも、自分で引き取ることもできます。発表では、プロンプトの書き換え、新しいユーザーインターフェース（UI）、組み込み機能の置き換え、新しい機能の追加ができる小さな TypeScript の関数で、自分で書くことも Claude Code に書かせることもできる、と説明しています。配布はプラグインとして行い、コマンドラインインターフェース（CLI）とデスクトップアプリで動きます（発表、Mods overview）。
ここに記載した内容は、公式発表および英語の公式ドキュメントで公開されている情報に基づいています。
こんなときはこの節へ
目的や困りごとから、該当する節へ移動できます。
| こんなとき | 読む節 |
|---|---|
| 定義と、使える版を確認したい | 何か・いつから使えるか |
| イベントを見る、書き換える、引き取る動きを知りたい | 仕組み |
| ターミナル以外でフックや描画が効くか知りたい | どこで動くか |
| 入れる、作る、共有する手順で迷った | 入れ方・作り方・共有 |
/diff などの組み込みを止めたとき、何が残るか知りたい | 組み込み mod |
| settings hook、Skill、Model Context Protocol（MCP）との違いを知りたい | hooks・Skill・MCP との違い |
| 信頼してよいか、組織の制限を確認したい | 信頼と制約 |
| 今日入れる前に見る項目がほしい | 導入チェックリスト |
何か・いつから使えるか
mod は、プラグインに同梱した JavaScript または TypeScript のイベントハンドラです。Claude Code v2.1.287 以降で使え、既定でオンです。入っている版は claude --version で確認します（Mods overview、Create a mod）。
ここで参照しているドキュメントのページは、v2.1.287 時点のものです。イベントやメソッドはリリースのあいだで変わり得るので、移行時に注意する変更は公式ドキュメントを参照してください。ページの記述と、インストール中の版が .claude-plugin/types/ に書いた型定義が食い違うときは、その型定義が優先です（Create a mod、Mods reference）。この記事は英語のドキュメントに沿っています。
早期アクセスで使われていた環境変数 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS を 0 にしても、v2.1.287 以降では mods はオフになりません。削除の案内は「hooks・Skill・MCP との違い」にまとめます。
仕組み
Claude Code は、何かをするたびにイベントを出します。例として、ツール呼び出し、権限の確認、画面の一部の描画があります。mod は、そのイベントにフックする関数です（発表）。
発表は、イベントの前、後、または代わりに実行でき、前後の両方で動く wrap もできる、と説明しています。ドキュメントは wrap という語より、next の前後に処理を置く説明を使っています。発表の前・後・代わり・wrap は、次の3つに対応します（発表、React to events）。
- 見る（observe）場合、先に仕事をさせるなら
next(e)を返します。イベントのあとで動くには、await next(e)してから処理し、その結果を返します。発表の「前」と「後」、および前後の両方で動く説明は、この呼び方に対応します。 - 書き換える（rewrite）場合は、イベントが深く凍結されているので、変更したコピーを
nextに渡します。 - 引き取る（answer）場合は、
nextを呼ばずに自分の結果を返します。後続の mod と、Claude Code 自身の振る舞いは走りません。発表の「代わり」はこちらに対応します。
発表が挙げる例には、モデルに届く前のプロンプトを書き換えること、ツール呼び出しを止める・書き換える・やり直すこと、権限の要求を承認または拒否すること、Claude が読む前のツール出力から秘密情報を除くこと、画面の一部を編集または置き換えること、ボタンや入力を足すことがあります。
ファイルの形は、通常のプラグインに hooks/hooks.json の modules が1つあることです。これがあると、そのプラグインは mod になります。最小構成は .claude-plugin/plugin.json、hooks/hooks.json、hooks/register.js です。モジュールは register(on, options) を export し、on(event, matcher?, hook) でフックを登録します。拡張子は .js、.mjs、.cjs、.jsx、.ts、.mts、.cts、.tsx で、ES module です。Node.js、バンドラ、ビルド手順は不要で、Claude Code が .js と .ts を直接読みます（Create a mod、Mods reference）。
フックの外へ出る操作は、引数 $ の mods API（Application Programming Interface、以下 API）だけが窓口です。描画、コマンドの追加、モデル呼び出し、ファイル、プロセス、ネットワークは、ここを通ります。フックモジュール自体には、Node.js の API も、setTimeout などのタイマーグローバルも、独自のネットワークやファイルアクセスもありません。URL、TextEncoder、AbortController、crypto.subtle などの標準的な JavaScript と Web の API は使えます（Use the mods API、Mods overview）。
イベント名の例は、ツールの tool.call、プロンプトの prompt.submit、UI の ui.render、ターンの turn.start、セッションの session.start です。settings hook と同じ出来事は、classic.Stop のように classic. が付きます。API のメソッド自体もイベントで、例は fs.read です。チェーン上で後ろにいる mod の呼び出しを、前の mod が観察したり、書き換えたり、拒否したりできます。名前の一覧は公式の Mods reference と React to events を参照してください。
読み込み順は、組み込みガード sec-default@builtin（読み込まれる場合）、managed settings の prependPlugins、その他組織の mod と数えられるもの、ユーザーがインストールした mod、appendPlugins、その他の組み込み mod、の順です。ユーザーが入れた mod 同士では、マニフェストの dependencies に書いた相手より前に走ります。同じイベントでは、最初に読み込まれた mod が最初に見て、結果を最後に見ます。managed settings の PreToolUse は、どの mod の tool.call よりも前に走り、そこでのブロックは最終です。それ以外の settings の PreToolUse と、プラグインの hooks/hooks.json にあるものは、最後の mod が next を呼んだあとの、Claude Code 自身の振る舞いの一部として走ります。ガードを読む条件は「信頼と制約」に書きます（React to events、Manage mods、発表）。
時間とサイズの上限の例として、1イベントあたりフック自身の実行は10秒（next や、$.clock.sleep 以外の mods API の待ちは含みません）、.catch は1秒、session.end は合計1.5秒、$.process.run は既定30秒で最長10分、$.fs.read と write は1ファイル4 MiB です。詳細は公式の Mods reference を参照してください。
どこで動くか
フックが走ることと、描画が見えることは別です。WSL は Windows Subsystem for Linux の略で、Windows 上で Linux 環境を動かす仕組みです。場所ごとのケースは次のとおりです（Mods overview）。
| 場所 | フック | 描画 |
|---|---|---|
ターミナルの claude（エディタ内蔵ターミナルと、JetBrains プラグインを含みます） | 走ります | 見えます |
| Desktop アプリの Code タブ（WSL セッションを除きます） | 走ります | 見えます（要素表が terminal のみとするものを除きます） |
| Desktop の WSL セッション | 走りません。WSL セッションではプラグインが使えないためです | 見えません |
| VS Code 拡張のチャットパネル | 走ります | 見えません |
claude -p と Agent SDK | 走ります | 見えません |
| claude.ai またはモバイルからの Remote Control | 手元のマシン上のセッションで走ります | 手元のターミナルに出ます |
| クラウドセッション | そのセッションに届くプラグインなら走ります | 見えません |
描画できる場所の例には、会話の横の Pane、プロンプト上の帯 AbovePrompt、Spinner があります。e.surface は terminal または desktop です。要素の例には Box、Text、Button、Input があります。Svg は Desktop のみで、Raster と Image は terminal 側の表に印があります。一覧は Mods reference を参照してください。
入れ方・作り方・共有
インストールはプラグインと同じです。セッション内では /plugin install <プラグイン名>@<マーケットプレイス名> を実行します。ドキュメントの例は token-chart@your-org です。シェルでは claude plugin install <名前>@<マーケットプレイス> を実行します。シェルから入れたときにセッションが開いていれば、そのセッションで /reload-plugins を実行します。開いていなければ、次回の起動時に読み込まれます。1セッションだけ試すには claude --plugin-dir <ディレクトリ> を使います。このフラグは繰り返せます（Mods overview、Create a mod、Mods reference）。
発表は、mods を含むプラグインを Claude directory から入れるか、CLI の /plugin で入れる、と書いています。ここで言う directory は claude.ai/directory です。提出先は claude.ai/directory/manage です。これはホームの ~/.claude ではなく、マーケットプレイスでもありません。ドキュメントは、directory から追加したプラグインはアカウント同期で Claude Code に届く、と区別しています。詳細は公式の Anthropic’s marketplaces を参照してください（発表）。
作り方は2つあります。手順の入口として、発表は導入ガイド Getting started with Claude Code mods をリンクしています。
対話セッションで Claude に頼むと、組み込みスキル plugin-authoring に沿って書きます。自分で /plugin-authoring を実行することもできます。置き場所は ~/.claude/dev-mods/<セッションID>/<mod名>/ です。最初のファイル保存時に、そのセッションでホットリロードを有効にするか聞かれます。有効にすると、ターンの終わりに読み込まれ、ファイルを変えたターンの終わりに再読み込みします。default と acceptEdits では、~/.claude が保護されたパスなので、ファイルを作る前に確認があります。Claude が書いた mod はそのセッションだけで読み込まれ、cleanupPeriodDays より古くなるとフォルダが削除されます。残すにはディレクトリをコピーし、claude --plugin-dir で読むか、マーケットプレイスに出します。プロンプトを出せないセッション（claude -p、dontAsk）、まだ信頼していないワークスペース、--safe-mode、--bare、disableAllHooks、組織の managed settings では読み込まれません（Create a mod）。
自分で書く場合のチュートリアルは first-mod です。ツール呼び出しを数えてスピナーの横に出し、/tally を足します。--plugin-dir で開いたディレクトリは、ファイルの変更で hooks module をホットリロードします。再読み込みのたびに register が再実行されるので、モジュール先頭の変数はリセットされます。セッションをまたぐ値には、$.state や $.store を使う、とドキュメントが案内しています（Create a mod、Use the mods API）。
API ガイドが説明している呼び出しには、$.command.register による / コマンド、$.tool.register によるツール、$.model.complete と $.model.fork、$.clock.every によるタイマー、$.ui.status と toast と log、$.session.send があります。発表が挙げる使い方には、継続的インテグレーションと継続的デリバリー（CI/CD）の状態を会話の横ペインに出すこと、本番設定に触れるコマンドの前に確認を求めること、最初に読み込まれる mod で他の mod の呼び出しを記録することがあります（Use the mods API、発表）。
読み込まれたかは、プロンプトで /plugin を開き、タブの下の薄い行で見ます。例は 1 mod active · first-mod です。この行は組み込み mod を含めません。組み込みは Installed の Built-in にあります（Mods overview）。
コードを実行せずに確認するには、claude plugin validate <ディレクトリ> を実行します。フックするイベントと、$ の呼び出しが一覧になります。claude plugin test は、セッションもサインインもネットワークもなしに、*.test.ts と *.test.tsx を走らせます。--plugin-dir や、Claude が書いた mod を読み込むたびに、その版の型定義が mod 内の .claude-plugin/types/ に書かれます。ドキュメントは、オンラインで見るならリポジトリの mods/types/claude-code.d.ts で、先頭行がその版を名指しする、と述べています（Create a mod、Mods reference）。
共有は、プラグインとしてマーケットプレイスに載せます。claude plugin validate は、claude- で始まる名前など、Anthropic 自身のものに見える名前を失敗させます。インストール済みのコピーはバージョンでキャッシュされるので、開発中は --plugin-dir を使い、配るときはバージョンを上げて入れ直します。発表は、プラグインに包んで directory に提出する、とも書いています（Create a mod、発表）。
概要が名前を挙げているサンプルは、token-weather、blast-radius、replay-theater です。token-weather はコンテキストウィンドウの予報をプロンプト上に描きます。blast-radius は危険なシェルコマンドを止め、差分を見せ、進めるか取り消すボタンを出します。replay-theater は直前ターンのファイル編集を /replay で追います。概要は、これらを claude-code-playground リポジトリの claude-code/mods に、サポートなしでそのまま共有している、と書き、クローンしたディレクトリを --plugin-dir で1セッション読み込むか、その claude-code/mods をマーケットプレイス claude-code-playground-mods として追加する、と説明しています（Mods overview）。
入れた mod を止める方法は、次のとおりです。1つだけ止めるには、/plugin の Installed から無効化するか、アンインストールします。そのセッションのインストール済み mod を全部止めるには、--safe-mode を使います。他のカスタマイズも無効になります。毎セッション止めるには、~/.claude/settings.json に "disableAllHooks": true を書きます。自分の settings hook とカスタムステータスラインも止まります。組織が管理しているものは動き続けます。disableAllHooks と、組織側の allowManagedModsOnly は mod だけを止めます。同じプラグインの skills、commands、agents、Model Context Protocol（MCP）サーバーは、読み込まれたままです（Mods overview）。組み込み mod が止まらない点は、次の節で扱います。
組み込み mod
一部の組み込み機能は、mod として出荷されています。/plugin の Installed にある Built-in の名前と、止め方は次のとおりです（Mods overview、Changelog）。
/plugin 上の名前 | 役割 | オフの仕方 |
|---|---|---|
cc-plugin-agents-md | AGENTS.md をプロジェクト指示として読みます。 | /plugin で無効化するか、読む指示ファイルを選びます。 |
cc-plugin-diff | /diff を引き取り、ペインを描きます。対話的なターミナルセッションでオンです。 | /plugin で無効化します。/diff 自体は残り、組み込み版が応答します。 |
cc-plugin-plugin-authoring | mod を書くための plugin-authoring スキルです。mod のコードは持ちません。 | /plugin で無効化します。 |
cc-plugin-sec-default | 組織が管理するものを、ユーザーが入れた mod から守ります。 | ユーザーはオフにできません。管理者が managed settings で順序を決めます。 |
cc-plugin-telemetry | Claude Code と組み込み mod の分析記録を送ります。 | /plugin で無効化するか、DISABLE_TELEMETRY などで分析をオフにします。 |
cc-plugin-you-should-know | 長めの作業中に脇で見るエージェントです。既定では無効です。 | /plugin enable cc-plugin-you-should-know@builtin で有効にします。 |
changelog の 2.1.287 は、このコマンドでオンにする旨を別項目で書き、telemetry がオンの first-party セッション向け、とも書いています（Changelog）。
disableAllHooks、--bare、--safe-mode は、インストールした mod を止めます。組み込み mod は止めません。管理向けのページは、--safe-mode がインストールされた mod を、組織のものも含めてオフにする、と述べています。disableAllHooks では、組織が管理しているものは動き続けます。組み込みの /diff をプラグイン側で無効化しても、コマンド /diff は残り、組み込み版が応答します（Mods overview、Manage mods）。
diff、agents-md、sec-default、telemetry のソースは、Claude Code リポジトリの mods ディレクトリに公開されている、とドキュメントと発表が述べています。発表がリンクしているツリーは anthropics/claude-code の mods です（Mods overview、発表）。
hooks・Skill・MCP との違い
mod はプラグインの一種です。hooks/hooks.json に modules があるプラグインが mod です。同じプラグインに、skill、settings hook、MCP サーバーを一緒に入れられます。マーケットプレイスの許可とブロックを含む、既存のプラグイン管理がそのまま適用されます（Mods overview、発表、Manage mods）。
概要の比較表は、何を変えられるかの違いを並べています（Mods overview）。
| 何か | 変えられるもの | UI を描けるか | 書くもの | |
|---|---|---|---|---|
| Mod | プラグイン内の関数です。Claude Code 自身のプロセスから呼ばれます。 | ツール呼び出し、プロンプト、コマンド、ターン、描画です。 | できます。 | JavaScript または TypeScript です。 |
| Settings hook | ライフサイクルのイベントで走るシェルコマンド、HTTP（ウェブのリクエスト）、プロンプトです。 | ツール呼び出しやプロンプトを進めるか、引数と結果、Claude 向けの追加コンテキストです。 | できません。 | スクリプトと settings.json です。 |
| Skill | Claude が読む SKILL.md です。 | Claude が知ることと、することです。 | できません。 | Markdown です。 |
| MCP サーバー | ツールを渡す外部プロセス、またはサービスです。 | Claude が持つツールです。 | できません。 | 任意の言語のサーバーです。 |
ドキュメントは、従来の hooks もイベントで走る、としたうえで、settings ファイルに書くシェルコマンド、HTTP、プロンプトを settings hook と呼び、mod の関数を hook と呼び分けています。settings hook は非推奨になっていません（Mods overview、Manage mods）。発表は、hooks ではイベントの書き換え、新しい UI、機能の置換ができず、mods ではできる、と違いを述べています。hooks の説明として、発表は Hooks をリンクしています（発表）。
MCP とは置き換えではなく、併用です。mod が $.tool.register したツールは、Claude から mcp__<プラグイン名>__<登録名> として見えます。$.mcp.call は、接続済みの MCP サーバーのツールを呼びます。$.mcp.connect は、自分のプラグインのマニフェストに書いた MCP サーバーを接続します（Use the mods API、Mods reference）。
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS を早期アクセス中に設定していた場合は、削除します。Claude Code v2.1.287 以降は、値にかかわらずこの変数を無視します。0 にしても mods はオフになりません。ドキュメントは、function hooks を現在の製品名としては定義しておらず、早期アクセス期に設定していた変数としてだけ言及しています。ユーザーが入れた mod を止める代替として、管理ページは allowManagedModsOnly を挙げています（Mods overview、Manage mods）。
信頼と制約
発表は、信頼について次のように書いています（発表）。
Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed, and you should only install mods from sources you trust, the same way you’d install any code on your computer.
近い言い方にすると、mods は Claude Code 自身と同じ範囲でマシンにアクセスし、サンドボックスされていません。コンピュータにコードを入れるときと同じように、信頼する提供元の mod だけを入れてください、という注意です。
ドキュメントも、mod は自分の権限で動くコードであり、ファイルの読み書き、プロセスの開始、ネットワーク要求ができる、と述べています。入れるのは、信頼する作者とマーケットプレイスだけにします。読み込んだあと、ユーザーアカウントができる範囲でファイルを読み書きし、プログラムを起動し、ネットワークへ出られます。環境変数と設定ファイルを参照でき、そこに置いた API キーも含まれます。セッション内のプロンプトとツール呼び出しをすべて見られ、プロンプトやツール呼び出しを書き換えられます。ユーザーが打ったかのようにプロンプトを送れ、他のセッションへメッセージを送れます。確認なしでツールを承認でき、プランまたは API キーを使えます（Mods overview）。
ドキュメントは「Mods aren’t sandboxed.」と書いたうえで、サンドボックスをオンにしても、隔離されるのは Claude が走らせる Bash コマンドであり、mod が起動したプロセスはその外で走る、と述べています。管理向けのページも、これらの制御は mod をサンドボックスせず、許可した mod はユーザーとして動く、としています（Mods overview、Manage mods）。
権限プロンプトの見た目は、mod から変えられません。ただし、プロンプトが出る前に、ツール呼び出しを承認したり拒否したりすることはできます。ask ルールで確認になる呼び出しや、managed settings 以外の自分の PreToolUse が止めた呼び出しは、承認する mod が承認できます。概要ページは、deny ルールを覆せる条件を、別ページ “Extend permissions with hooks” に委ねています。管理ページが述べている範囲では、ガードが読み込まれる環境では、ユーザーの mod は deny ルールが拒否した呼び出しを承認できず、managed の PreToolUse のブロックも最終です。allowModsToOverrideDenyRules を true にすると、ユーザーの mod が deny ルールの拒否を承認できるようになります。未設定では deny が優先します。この制限は Claude のツール呼び出しに対するもので、mod 自身の $.fs と $.process には及びません。Read(.env) を deny していても、mod は $.fs.read や、それを行うプログラムの起動で読めます（Mods overview、Manage mods）。
入れる前に、ファイルを取って claude plugin validate ./some-mod を実行すると、実行せずに hooks: と calls: が出ます。静的解析で読めない mods API の使い方をする mod は、Claude Code が読み込みを拒否します（Mods overview、Manage mods）。
組織側では、mods はオンです。プラグイン設定が許すマーケットプレイスから入れるか、--plugin-dir でディレクトリから読めます。組み込みガード sec-default@builtin（/plugin では cc-plugin-sec-default）は、マシンに managed settings があるか、Team または Enterprise プランでサインインしているときに、ユーザーが入れた mod より前に読み込まれます。ユーザーはオフにできません。API キー、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry の利用者は、managed settings があるマシンだけでこのガードを得ます（Manage mods、発表）。
ガードは、managed hooks が受け取るものや決定、システムプロンプト、managed の CLAUDE.md など設定として読まれるもの、managed MCP サーバーのツールと説明を、ユーザーの mod が変えることを止めます。それ以外の制限は、既定では追加しません。prependPlugins を managed settings で自分で置いた場合、ガードはリストに名前があるとき、その位置でのみ読み込まれます。制限を残すなら sec-default@builtin をリストに入れます。pluginConfigs のキーは cc-plugin-sec-default@builtin です。発表が “loads first” や “add sec-default to your list” と書いている点は、この「prependPlugins を設定したときだけ、名前がある位置で読み込まれる」と合わせて読んでください（Manage mods、発表）。
発表は、Team と Enterprise ではオーナーが管理コンソールでプラグインマーケットプレイスの許可またはブロックを設定し、Claude API とサードパーティ API のプランでは管理者が managed settings を利用者のマシンへ配る、と書いています。ユーザーが入れた mod を全部止めるには、managed settings でガードの allowManagedModsOnly を true にします。--plugin-dir と、セッション中に Claude が書いた mod も対象です。settings hook、ステータスライン、/goal、組み込み mod は残ります。ユーザー側の settings に同じ項目を書いても効きません。disableSideloadFlags は、起動時の --plugin-dir と --plugin-url を拒否し、セッション中に Claude が書いた mod も読み込ませません。--agents と --mcp-config も拒否します（発表、Manage mods）。
Web fetch を組織がオフにしているとき、またはセッションで非必須のネットワークがオフのとき、$.http.fetch は拒否されます。$.process.run で起動したプログラムは、ユーザー自身のネットワーク到達のままです。まだ信頼していないディレクトリの対話セッションでは、信頼プロンプトに答えるまで mod は読み込まれません（Manage mods）。
導入チェックリスト
今日 mod を入れるなら、次を上から確認します。
- 版を見る。
claude --versionが v2.1.287 以降かどうかを確認します。mods はこの版から既定でオンです。 - 作者を信頼する。 自分のマシンで動くコードとして、作者と提供元を信頼できる場合だけ入れます。mods はサンドボックスされていません。Bash のサンドボックスをオンにしても、mod が起動したプロセスは隔離されません。
- 実行前に検証する。
claude plugin validateで、フックするイベントと$の呼び出しを見ます。 - 描画の場所を知る。 フックが走る場所と、描画が見える場所は別です。Desktop の WSL セッションではプラグインが使えません。VS Code のチャットパネル、
claude -p、Agent SDK、クラウドセッションでは描画は見えません。 - 組み込みが残ることを知る。
disableAllHooks、--bare、--safe-modeは組み込み mod を止めません。cc-plugin-diffを無効化しても/diffは残り、組み込み版が応答します。cc-plugin-you-should-knowは既定でオフです。 - 古い環境変数を消す。
CLAUDE_CODE_ENABLE_FUNCTION_HOOKSが残っていれば削除します。値を0にしても、v2.1.287 以降では無視され、mods はオフになりません。
出典
詳細は次の公式ページを優先して確認してください。