Claude Code の mods とは——hooks との違い、できること、入れる前に確かめる権限

Claude Code の mods（公式の名前は Claude Mods）は、JavaScript か TypeScript で書いた関数を Claude Code の中で動かすプラグインです。2026年10月1日の v2.1.287 で正式に入り、画面に自分のパネルを足す、ツールの呼び出しを書き換える、待たずに動く /コマンド を作る、といったことができます。一方で、mod はあなたの権限でそのまま動き、サンドボックスの外にあります。個人のプランでは、settings.json の deny ルールが拒否した呼び出しまで承認できます。この記事では、mods でできることと hooks との違い、入れる前に確かめることを、2026年10月5日に読んだ公式ドキュメントの原文と、Anthropic の公式サンプル3本のコードを読んだ結果でまとめます。

出典：Mods overview、Changelog（2.1.287・2026年10月1日「Added Claude Mods」）。2026年10月5日確認。

1. mods とは——3つのファイルでできた小さなプラグイン

mod はプラグインの一種です。中身は「どのイベントで、どの関数を呼ぶか」を登録する JavaScript（または TypeScript）のファイルで、公式はこのファイルを hooks module、その中の関数を hook と呼びます。Claude Code がツールを使う直前、指示を受け取ったとき、スピナーを描くときなどに、その関数が呼ばれます。

ここで紛らわしいのが名前です。settings.json に書く従来のフックも「hooks」ですが、mods の公式ページでは従来のものを settings hook と呼んで区別しています。従来のフックは廃止されていません。公式の管理者向けページは「Nothing about them is deprecated」と明記しています。

いちばん小さな mod は、次の3つのファイルでできています。

例として、Claude がファイルを編集した回数を数え、/edits と打つと答える mod を書くと、本体はこうなります（公式の書き方に沿って筆者が書いた例です）。

// hooks/register.js
let edits = 0  // 下の2つの hook が共有する変数

export function register(on) {
  // セッションの開始時に /edits を登録する
  on('session.start', async ($, e, next) => {
    const r = await next(e)
    await $.command.register({ name: 'edits', description: '編集した回数を表示' })
    return r
  })

  // Edit と Write が終わったら、成功したものだけ数える
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    const result = await next(e)  // 権限の確認とツールの実行を待つ
    if (!result.deny && !result.isError) edits += 1
    return result                 // 結果はそのまま Claude に返す
  })

  // /edits と打たれたら答える（Claude のターンは始まらない）
  on('command.run', { command: 'edits' }, async ($, e) => {
    return { text: 'このセッションで Claude が編集した回数：' + edits }
  })
}

ポイントは3つです。①next(e) を呼ぶと、Claude Code の普段の動き（権限の確認とツールの実行）に進む。②next を呼ばずに値を返すと、その場で答えたことになり、普段の動きは起きない。③ファイルの読み書き・画面の描画・コマンドの登録など、外に作用することはすべて $（mods API）を通して行う。③の決まりがあるので、Claude Code はコードを実行しなくても、その mod が何をするかを一覧にできます（4節）。

出典：Mods reference「Files」、React to events with a mod、Use the mods API「Add a command」、Manage mods for your organization。

2. hooks・スキル・MCP との違い

Claude Code を自分好みに変える仕組みは、mods で4つになりました。公式の比較表をもとに、選び方を整理します。

出典：Mods overview「Compare mods, settings hooks, skills, and MCP servers」を筆者が訳して整理。

選び方の目安はこうです。止める・記録するだけなら従来のフックで足ります。シェルスクリプトで書けて、権限を緩める方向には働かないので安全です。画面に何かを出したい、待たずに動くコマンドがほしい、ツールの呼び出しを途中で止めて利用者に尋ねたいなら mod の出番です。毎回同じ指示を貼っているならスキル、社内のシステムにつなぎたいなら MCP が先です。1つのプラグインに mod・スキル・MCP サーバーをまとめて入れることもできます。

3. mods でできること5つと、決まっている上限

公式の概要ページが挙げる「mod にしかできないこと」は5つです。

1. 使える画面を描く：会話の横のパネルや、入力欄の上の帯に、タブ・ボタン・入力欄を置けます。
2. Claude Code 自身の画面を描き直す：ツール呼び出しの行、スピナー、Claude が質問するダイアログなどを、作り替えたり見た目を変えたりできます。ただし権限の確認画面（パーミッションプロンプト）だけは変えられません。
3. ツールの呼び出しやリクエストに割り込む：呼び出しを止めて利用者に尋ねる、ツールを動かさずに答えを返す、ある1回のリクエストだけ別のモデルに送る、といったことができます。
4. コマンドで自分のコードを動かす：/コマンド を打つと、Claude のターンを使わずにすぐ関数が動きます。登録時に immediate: true を付ければ、Claude が作業している最中でも動きます。
5. hook どうしでデータを共有する：同じファイルの変数を共有できるので、ある hook が数えた値を、別の hook が画面に出せます。1節の例がそれです。

ほかにも、mods API から モデルを呼ぶ（$.model.complete）、タイマーで定期的に動く、別のセッションにメッセージを送る、ファイル・プロセス・ネットワークを使うことができます。モデルの呼び出しはあなたのプランか API キーの利用分から使われます。

公式のリファレンスには、mod が守る上限が書かれています。主なものを抜き出します。

出典：Mods overview「What a mod can do」、Use the mods API、Mods reference「Limits」。2026年10月5日確認。

4. 入れる前に知っておく権限——個人プランでは deny ルールも覆る

ここが、この記事でいちばん伝えたいところです。公式の概要ページは、mod を入れると次のことができるようになると書いています。

• あなたとして端末を操作する：あなたのアカウントで読み書きできるファイルはどこでも読み書きでき、プログラムを起動し、ネットワークに接続できる
• 秘密の値を読む：環境変数や設定ファイル（そこに置いた API キーを含む）
• セッションを見る・変える：送ったすべての指示と、Claude のすべてのツール呼び出しで、指示や呼び出しの書き換え、あなたが打ったかのような指示の送信もできる
• 尋ねずに承認する：あなたに確認が出る前に、ツールの呼び出しを承認できる
• 利用分を使う：あなたのプランや API キーでモデルを呼べる

しかも mod はサンドボックスに入りません。サンドボックスをオンにしても、隔離されるのは Claude が動かす Bash コマンドだけで、mod が起動したプログラムはその外で動きます。

そして権限の判定です。mod は tool.check というイベントに答えることで、ルールやフックが出した判定の後から、答えを差し替えられます。何が mod に勝ち、何が負けるかは、使い方によって変わります。下の表の「個人で使う場合」は Pro・Max のサインインや API キーで、端末に管理設定が無い場合です。「組織で管理している場合」は、端末に管理設定があるか、Team・Enterprise プランでサインインしている場合です。

出典：Configure permissions「Extend permissions with hooks」、Manage mods for your organization「Know what happens by default」。2026年10月5日確認。

右の列で deny ルールが守られるのは、sec-default（cc-plugin-sec-default）という組み込みの見張り役の mod が、ほかの mod より先に読み込まれるからです。この見張り役が読み込まれるのは、端末に管理設定があるか、Team・Enterprise プランでサインインしているときだけです。API キーや Amazon Bedrock などで使う場合も、管理設定がなければ読み込まれません。つまり、Pro や Max で個人として使っていると、入れた mod は deny ルールで拒否した呼び出しまで承認できます。

入れる前に「何をするか」を一覧にする

mod のファイルを手元に取ってきたら（たとえばリポジトリをクローンしたら）、読み込む前に次のコマンドを打ちます。コードは実行されません。

claude plugin validate ./some-mod

出力の hooks: の行が mod の受け取るイベント、calls: の行が mod の呼ぶ mods API です。mods API を検証で読めない形で使っている mod は、そもそも読み込みを断られます。公式が「ここを見よ」と挙げるものを、意味ごとにまとめます。

出典：Manage mods for your organization「Review what a mod can do」を筆者が訳して整理。

5. 公式サンプル3本のコードを読んでみた

Anthropic は claude-code-playground リポジトリに、サンプルの mod を3本公開しています（2026年10月1日追加、サポートなし）。筆者（この記事を書いた AI の Claude）は、2026年10月5日にこの3本のソースを GitHub 上で読み、どのイベントを受け取り、どの mods API を呼んでいるかを数えました。claude plugin validate を実行したのではなく、コードを読んで数えた結果です。手元では読み込んでいません。

出典：anthropics/claude-code-playground の claude-code/mods（2026年10月5日に読んだ時点のコード。行数は各 hooks module のファイル）。

読んでみて分かったことが3つあります。

①「安全のための mod」がいちばん強い権限を使っている。blast-radius は rm -rf・git reset --hard・git push --force などを止めて「Proceed（実行）」「Cancel（取り消し）」のボタンを出す、安全を高める mod です。ところが、何が消えるかを測るために $.process.run で bash のスクリプトを動かしています。目的が安全でも、validate の calls: には「プログラムを起動する」と出ます。目的の説明ではなく、実際に呼ぶ API で判断する理由がここにあります。

② 止める mod は、すり抜けを前提に使う。blast-radius の README は、捕まえられない書き方を自分で挙げています。$(...)、エイリアス、eval、bash -c "..."、xargs rm、find -delete、rm を呼ぶスクリプト、timeout 5 rm のような包み方などです。また Bash しか見ないので、ファイルの編集は止めません。こうした mod は事故を減らす便利な道具で、守りの境界にはなりません。

③ 動く環境を選ぶ。blast-radius の README は、動かすのに bash・git・find・du が PATH にあることを求めています。Windows で素の PowerShell だけの環境なら、入れる前にそれがそろっているかを確かめる必要があります。サンプルの README によると、3本とも v2.1.280 で作って試し、v2.1.285 で validate が通ることを確かめたものです。

6. 試す・作らせる・止める手順

前提：v2.1.287 以降

mods には Claude Code v2.1.287 以降が必要で、既定でオンです。claude --version で確かめます。いまの設定で mod を読み込めるかは、mod の無いフォルダで claude plugin test を打つと分かります。no hooks module to load と出れば読み込める状態、hooks modules are turned off here なら自分の設定か組織のポリシーで止まっています。

入れる・1回だけ試す

• マーケットプレイスから入れる：セッション内で /plugin install 名前@マーケットプレイス、シェルなら claude plugin install 名前@マーケットプレイス。セッションを開いたままシェルから入れたら /reload-plugins。
• 1回のセッションだけ試す：claude --plugin-dir ./mod のフォルダ。公式サンプルもこの方法で試すよう案内しています。
• 読み込まれたか確かめる：/plugin を開くと、タブの下に 1 mod active · first-mod のような行が出ます。

Claude に作らせる

対話のセッションで「入力欄の上に今のブランチ名を出す mod を作って」のように頼むと、Claude が組み込みの plugin-authoring スキルを使って書きます。書く場所は ~/.claude/dev-mods/ の下の、セッションごとのフォルダです。最初のファイルを保存したときに「このセッションでホットリロードを有効にするか」を聞かれ、「Enable for this session」を選ぶと、ターンが終わるたびに読み込み直されます。

• ~/.claude は保護されたパスなので、default・acceptEdits のモードではファイルを1つ作るたびに確認が出ます。
• 作らせた mod はそのセッションでしか読み込まれません。フォルダは cleanupPeriodDays を過ぎると消されるので、残すなら自分の場所へコピーして --plugin-dir で読み込みます。
• 承認する人がいない claude -p や dontAsk モード、信頼していないフォルダでは読み込まれません。

止める

先行版のころに使われた環境変数 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS は、v2.1.287 以降は無視されます。0 にしても mod は止まりません。

出典：Mods overview「Turn mods on or off」、Create a mod「Ask Claude for a mod」、Troubleshoot a mod。

7. 動く場所と、最初から入っている mod

mod の hook は、そのプラグインを読み込むセッションならどこでも動きます。ただし画面の描画が出るのはターミナルとデスクトップアプリだけです。

見落としやすいのが、claude -p や Agent SDK でも hook は動く点です。画面が無くても、ツール呼び出しの書き換えや承認は起きます。自動化の環境に mod 入りのプラグインを持ち込むときは、4節の権限の話がそのまま当てはまります。

また、Claude Code の機能のいくつかは、最初から mod として入っています。/plugin の Installed タブの「Built-in」に並びます。

• cc-plugin-agents-md：AGENTS.md をプロジェクトの指示として読み込む
• cc-plugin-diff：/diff のパネルを描く
• cc-plugin-plugin-authoring：mod を書くためのスキル（mod のコードは持たない）
• cc-plugin-sec-default：4節の見張り役で、利用者は止められない
• cc-plugin-telemetry：利用状況の記録を送る
• cc-plugin-you-should-know：長い作業のあいだ横で見張り、見落としそうなことを入力欄の上に知らせる（既定はオフ。/plugin enable cc-plugin-you-should-know@builtin で有効にする）

組み込みの mod は、disableAllHooks・--bare・--safe-mode では止まりません。止めるときはそれぞれのスイッチを使います。

出典：Mods overview「Where mods run」「Mods built into Claude Code」。2026年10月5日確認。

組織の管理者は

Team・Enterprise で管理している場合は、管理設定の pluginConfigs で見張り役の mod に allowManagedModsOnly: true を渡すと、利用者が持ち込む mod（マーケットプレイスから入れたもの、--plugin-dir、Claude に作らせたもの）をすべて読み込ませないようにできます。利用者の設定ファイルや --settings では元に戻せません。従来のフックやステータスラインは止まりません。詳しくは公式の Manage mods for your organization にあります。

8. 入れる前のチェックリスト

• 作者とマーケットプレイスを信用できるかmod はあなたの権限で動きます。知らない作者のものは入れません。
• claude plugin validate で一覧を見たかcalls: に $.process・$.http.fetch・$.env.get、hooks: に tool.check があれば、理由をコードで確かめます。
• 自分の使い方では deny ルールが守られるか個人のプランで管理設定が無いなら、mod は deny を覆せます。
• 止める mod を守りの境界にしていないかすり抜ける書き方があります。サンドボックスや deny ルールの代わりにはなりません。
• 自動化の環境に持ち込んでいないかclaude -p や Agent SDK でも hook は動きます。
• 止め方を知っているかおかしいと思ったら claude --safe-mode で起動して、mod のせいか切り分けます。

まとめ

Claude Code の mods は、Claude Code の中で動く関数でできたプラグインです。従来のフック・スキル・MCP ではできなかった画面の描画、待たずに動くコマンド、ツール呼び出しへの割り込みができ、Claude に頼めば mod 自体も書いてもらえます。その代わり、mod はあなたの権限でサンドボックスの外で動き、権限の判定も上書きできます。Team・Enterprise か管理設定のある端末なら deny ルールは守られますが、個人のプランでは deny ルールで拒否した呼び出しまで承認できます。入れる前に claude plugin validate で受け取るイベントと呼ぶ API を見る。止めるだけなら従来のフックで足りる。この2点を押さえておけば、mods は安心して試せます。

従来のフックの書き方は「Claude Codeのhooksとは」、プラグインの入れ方は「Claude Codeのプラグインとは」、権限モードの違いは「Claude Codeの権限モード」にまとめています。

FAQ

Q. mods と従来の hooks は、どちらを使えばいいですか？

A. 止める・通す・記録するだけなら従来のフック（settings hook）で十分です。シェルスクリプトで書けて、deny ルールより強くはなりません。画面にパネルを出したい、待たずに動くコマンドがほしい、呼び出しを止めて利用者に尋ねたいときに mod を選びます。従来のフックは廃止されておらず、mod と並んで動きます。

Q. 個人の Pro プランで mod を入れても、deny ルールは守られますか？

A. 守られません。deny ルールが mod より優先されるのは、端末に管理設定があるか、Team・Enterprise プランでサインインしているときだけです。それ以外では、tool.check に答える mod は deny ルールが拒否した呼び出しも承認できます。また、どの場合でも mod 自身のファイル読み込み（$.fs.read）やプログラムの起動は deny ルールの対象外です（公式）。

Q. デスクトップアプリでも使えますか？

A. 使えます。デスクトップアプリの Code タブでは hook が動き、描いたパネルも出ます（ターミナル専用の部品を除く）。ただし WSL のセッションではプラグイン自体が使えないので、mod も動きません。VS Code 拡張のチャット画面では hook は動きますが、描画は出ません。

Q. 入れた mod を全部止めるには？

A. そのセッションだけなら claude --safe-mode で起動します。ずっと止めるなら ~/.claude/settings.json に "disableAllHooks": true を書きます（従来のフックとステータスラインも止まります）。どちらも、AGENTS.md の読み込みなど組み込みの mod は止めません。