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

# mod リファレンス

> Claude Code の mod の完全なリファレンス：フックモジュールの構成、イベント、mods API メソッド、描画箇所、サーフェス別の要素、制限、設定。

[mod](https://code.claude.com/docs/ja/plugins/mods/overview.md) が処理できるイベント、呼び出せる mods API メソッド、描画できる描画箇所を調べられます。各項目は v2.1.290 時点の Claude Code CLI と Desktop アプリ、および v2.1.299 時点の VS Code 拡張機能を対象としています。各項目には名前と 1 行の説明があり、解説しているガイドのセクションがある場合はそこへのリンクも記載しています。

> [!NOTE]
>
> 完全なリファレンスは Claude Code の [mod 用 TypeScript 宣言](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)で、すべてのイベント、メソッド、要素が例とともに記述されています。GitHub 上のコピーは、インストールしている Claude Code のバージョンより古い場合があります。両者が食い違う場合は、[Claude Code がお使いのバージョン用に書き出すコピー](https://code.claude.com/docs/ja/plugins/mods/create.md#get-the-types-for-your-build)を信頼してください。

## ファイル

mod は、次のファイルを含むプラグインディレクトリです。

| ファイル | 必須 | 内容 |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | はい | プラグインの[マニフェスト](https://code.claude.com/docs/ja/plugins/manifest-reference.md)。mod によって追加される必須フィールドはありません。 |
| `hooks/hooks.json` | はい | `modules`：フックモジュールへのパスを 1 つ含む配列で、パスはこのファイルからの相対パスです（例：`"modules": ["./register.js"]`）。`hooks` の下に[設定フック](https://code.claude.com/docs/ja/hooks.md)を置くこともできます。 |
| [`hooks/register.js`](https://code.claude.com/docs/ja/plugins/mods/create#write-a-mod-yourself) などのフックモジュール | はい | mod のエントリポイント。`register(on, options)` をエクスポートします。名前は `.js`、`.mjs`、`.cjs`、`.jsx`、`.ts`、`.mts`、`.cts`、`.tsx` のいずれかで終わります。ES モジュールです。 |
| [`types/index.d.ts`](https://code.claude.com/docs/ja/plugins/mods/interface#declare-the-values)（マニフェストの `types` で別のパスを指定している場合はそのパス） | mod が `$.state` を使う場合、または mods API に名前空間を追加する場合 | `PluginState` の値と、mod が追加する名前空間を宣言します。マニフェストで `types` を省略するには、v2.1.299 以降が必要です。 |
| 名前が `.test.ts` または `.test.tsx` で終わるファイル | いいえ | [`claude plugin test`](https://code.claude.com/docs/ja/plugins/mods/test#write-a-test) が実行するテスト |

`register` は `on` と `options` を受け取ります。`options` には、マニフェストが宣言する [`userConfig`](https://code.claude.com/docs/ja/plugins/components#user-configuration) フィールドの値が、デフォルト値を補った状態で入っています。

## フック関数

mod は、イベントハンドラーである各フックを `register` 内で `on` を呼び出して登録します。`on` は、イベント名、省略可能な [matcher](https://code.claude.com/docs/ja/plugins/mods/events.md#filter-which-events-a-hook-handles)（イベントのフィールドに対するフィルター）、フックを受け取ります（例：`on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))`）。`on` は、フックの[エラーハンドラー](https://code.claude.com/docs/ja/plugins/mods/events.md#handle-a-hook-that-fails)を設定する `.catch(handler)` メソッドを 1 つだけ持つ登録オブジェクトを返します。

| 引数 | 内容 |
| :- | :- |
| [`$`](https://code.claude.com/docs/ja/plugins/mods/events#how-a-hook-handles-an-event) | mods API：[mods API メソッド](#mods-api-methods)のすべてのメソッド。各呼び出しは、名前空間、メソッドの順に省略せずに書きます（例：`$.fs.read('notes.md')`）。 |
| [`e`](https://code.claude.com/docs/ja/plugins/mods/events#how-a-hook-handles-an-event) | イベントの入力。深く凍結されたプレーンなデータです。変更するには、コピーを `next` に渡します。 |
| [`next(e)`](https://code.claude.com/docs/ja/plugins/mods/events#how-a-hook-handles-an-event) | ミドルウェアと同様の次のハンドラー。このフックの後のフックを実行し、次に Claude Code の動作を実行します。イベントの結果に解決されます。 |
| [`next.signal`](https://code.claude.com/docs/ja/plugins/mods/api#stop-background-work) | イベントが破棄されたときに中止される `AbortSignal` |
| `next.origin` | イベントを発火したものの `{ plugin, tier }`。Claude Code 自身は `{ plugin: 'engine', tier: 'core' }` です。mod の `tier` は、[mod が実行される順序](https://code.claude.com/docs/ja/plugins/mods/events.md#the-order-mods-run-in)における優先度グループで、`prepend`、`user`、`append`、`builtin` のいずれかです。 |
| `next.budget` | フックの制限時間（ミリ秒）：`next.budget.ms` は制限全体、`next.budget.remainingMs` は現時点の残り時間です |
| `next.to(e, tier)` | 後の tier（`append`、`builtin`、`core` のいずれか）までスキップします。`next.to(e, 'append')` はユーザーがインストールした mod をスキップします。呼び出せるのは `prependPlugins` または `appendPlugins` にある mod だけです。 |
| `next.error` | `.catch` ハンドラー内でのみ使用できます。`kind` は `throw` または `timeout` で、`message` はエラーのテキストです。 |
| `next.called` | `.catch` ハンドラー内でのみ使用できます。フックが `next` を呼び出していた場合は `true` です。 |

## イベント

イベントは対象ごとにグループ化されており、それぞれ発火するタイミングと、そのイベントのフックが返せる値を記載しています。`turn.step` と `process.spawn` のフックは非同期ジェネレーターで、それ以外のフックは非同期関数です。

各表の最後の列では略記を使っています。`next(e)` はイベントを変更せずに渡します。`next({ ...e, text })` は、指定したフィールドを変更したコピーを渡します（例：`next({ ...e, text: e.text.trim() })`）。オブジェクトは `next` を呼び出さずにイベントに応答し、`reason` などの語はユーザーが書く文字列を表します（例：`{ deny: 'Use the file tools.' }`）。

### ツール

ツールイベントは、Claude が読む説明から呼び出しを実行するかどうかの判定まで、Claude が行う各ツール呼び出しの前後で発火します。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`tool.call`](https://code.claude.com/docs/ja/plugins/mods/events#guard-or-change-a-tool-call) | ツールが実行される直前 | `next(e)`、`{ deny: reason }`、または `{ result }` |
| [`tool.check`](https://code.claude.com/docs/ja/plugins/mods/events#where-settings-hooks-run-in-the-order) | `tool.call` フックと `PreToolUse` フックの後、Claude Code がツール呼び出しを実行してよいかを判定するとき。`next(e)` は、ルール、権限モード、それらのフックが下した判定に解決されます。 | `next(e)` または `{ decision }`（`decision` には `allow`、`ask`、`deny` のいずれかを設定し、任意で `reason` を指定できます） |
| `tool.describe` | 各ツールにつき 1 回、その説明が初めて Claude に送信されるとき。MCP ツールの場合は、Claude が[ツール検索](https://code.claude.com/docs/ja/mcp.md#scale-with-mcp-tool-search)を通じてそのツールを読み込むときに 2 回目が発火し、`e.description` には読み込まれたツールについて Claude が読むテキストが設定されます。 | `{ description }`（任意で `isDeferred` を指定でき、`true` にするとツールをツール検索の背後に置き、`false` にすると最初から読み込みます）。変更した説明を次のターンで送信するには、[`breakPromptCache: true`](#break-prompt-cache) を追加します。 |

#### `tool.check` のエージェントと組織のフィールド

`tool.check` フックでは、次のフィールドを読み取ることで、サブエージェントによる呼び出しとメインの会話による呼び出しを区別したり、組織がコネクタツールに承認を必要としているかどうかを確認したりできます。

* **`e.agentId`**: [サブエージェント](https://code.claude.com/docs/ja/sub-agents.md)または[インプロセスのチームメイト](https://code.claude.com/docs/ja/agent-teams.md#choose-a-display-mode)が呼び出しを行う場合に設定され、メインの会話が呼び出しを行う場合は存在しません
* **`e.ceiling`**: [その設定が Claude Code に届くセッション](https://code.claude.com/docs/ja/mcp.md#organization-controls-on-connector-tools)で、組織が `ask` に設定したコネクタツールの場合は `ask`

`tool.check` の `e.agentId` と `e.ceiling` には Claude Code v2.1.290 以降が必要です。

#### `tool.check` の `e.isReadOnly` フィールド

`tool.check` フックでは、ツールがこの呼び出しを読み取り専用と報告した場合に `e.isReadOnly` が `true` になります。それ以外の場合、このフィールドは `false` ではなく存在しません。この値はツール自身の報告であるため、このフィールドだけに基づいて呼び出しを承認する前に、[ツール呼び出しが読み取り専用かどうかを確認する](https://code.claude.com/docs/ja/plugins/mods/events.md#check-whether-a-tool-call-is-read-only)を読んでください。

`tool.check` の `e.isReadOnly` には Claude Code v2.1.304 以降が必要です。

### プロンプトと Claude が読むもの

プロンプトイベントは、ユーザーが入力するテキストと、システムプロンプトやリマインダーなど Claude Code が独自に Claude へ送信するテキストを対象とします。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`prompt.submit`](https://code.claude.com/docs/ja/plugins/mods/events#rewrite-or-add-to-a-prompt) | プロンプトが送信されるとき | `next({ ...e, text })`、`next({ ...e, context })`、または `{ drop: reason }` |
| `prompt.fill`、`prompt.suggest` | テキストが下書きとして、または薄い表示の候補としてプロンプトボックスに入る直前 | テキストを変更した `next(e)` |
| `prompt.edit` | ユーザーがプロンプトボックスを編集するとき | `next(e)` |
| `prompt.autocomplete` | ユーザーがプロンプトボックスに入力し、カーソル位置で単語が終わるとき。`e.token` はその単語です。Claude Code はフックを待たず、Claude Code 独自のオートコンプリートの行が先に表示されます。 | `{ suggestions }`（Claude Code 独自の行の下に表示される `{ text, label, description }` の行のリスト）。行を選択すると、その `text` で単語が上書きされます。 |
| `prompt.compose` | Claude Code がシステムプロンプトを生成するとき | `{ sections }`（送信順に並んだ `{ id, text, scope }` のリスト） |
| [`prompt.section`](https://code.claude.com/docs/ja/plugins/mods/events#rewrite-or-add-to-a-prompt) | システムプロンプトの名前付きセクションごとに 1 回。`e.name` は `prompt.compose` におけるそのセクションの `id` です。 | `{ text }`、またはセクションを省くには `{ text: null }`。変更したセクションを次のターンで送信するには、[`breakPromptCache: true`](#break-prompt-cache) を追加します。 |
| [`prompt.context`](https://code.claude.com/docs/ja/plugins/mods/events#rewrite-or-add-to-a-prompt) | 会話ごとに 1 回、最初のメッセージとともに送信されるコンテキストについて | `{ blocks }` |
| `prompt.attachment` | Claude Code がリマインダーなど独自のメッセージを Claude 向けに追加するとき。`e.type` は種類を示し、型で宣言されている種類については、テキストの元になった事実が `e.detail` に入っています。 | `{ text }`、または省くには `{ text: null }` |
| `prompt.mention` | プロンプトで @ メンションされたファイルを Claude Code が読み込む直前。Claude Code v2.1.290 以降が必要です。 | 別のファイルを読み込むには `next({ ...e, path })`、または `{ deny: reason }` |
| [`skill.prompt`](https://code.claude.com/docs/ja/plugins/mods/events#rewrite-or-add-to-a-prompt) | スキルのテキストが Claude 向けに展開されるとき | `{ text }` |
| `attribution.text` | Claude Code がコミットまたはプルリクエストの帰属テキストを作成するとき | `{ text }` |

#### `skill.prompt` のソースとフロントマターのフィールド

`skill.prompt` フックでは、`e.skill` のスキル名と `e.text` の Claude が読むテキストに加えて、次のフィールドを読み取れます。

| フィールド | 型 | 内容 |
| :- | :- | :- |
| `e.source` | string | スキルの提供元。エンタープライズ、個人、プロジェクトの[場所](https://code.claude.com/docs/ja/skills.md#where-skills-live)にあるスキルの場合は、それぞれ `policySettings`、`userSettings`、`projectSettings` です。その他の提供元では、`plugin`、`mcp`、`syncedSkills`、`built-in` などの語になります。 |
| `e.pluginName` | string | `e.source` が `plugin` であるスキルの場合、そのプラグインの名前 |
| `e.path` | string | スキルの `SKILL.md` ファイルの絶対パス。[コマンドファイル](https://code.claude.com/docs/ja/skills.md#where-skills-live)として書かれたスキルの場合は、その `.md` ファイルの絶対パス。組み込みスキルのように、このマシン上にファイルがないスキルの場合は存在しません。 |
| `e.frontmatter` | object | スキルのファイルのフロントマター（プレーンなデータとして） |
| `e.frontmatterProblem` | string | `e.frontmatter` にファイルのフロントマターまたはそのキーのいずれかが欠けている理由（例：`is a list or a single value, not a table`）。`e.frontmatter` がフロントマター全体を保持している場合、またはスキルにフロントマターがない場合は存在しません。 |

フックは変更した `text` または `frontmatter` を `next` に渡せます。後続のフックは両方を読み取り、Claude は最終的な `text` を読みます。それ以外のフィールドを変更したフックは[失敗](https://code.claude.com/docs/ja/plugins/mods/events.md#handle-a-hook-that-fails)します。

`skill.prompt` の `e.source`、`e.pluginName`、`e.path`、`e.frontmatter`、`e.frontmatterProblem` には Claude Code v2.1.299 以降が必要です。

#### `breakPromptCache` で変更したシステムプロンプトのセクションまたはツールの説明を送信する

実行中の会話でセクションまたはツールの説明を変更するには、`$.ui.invalidate('prompt.section')` または `$.ui.invalidate('tool.describe')` を呼び出してフックを再実行させます。そのフックから `{ text, breakPromptCache: true }` または `{ description, breakPromptCache: true }` を返します。このフィールドがない場合、セクションまたは最初から読み込まれるツールについて、Claude は新しい会話または[コンテキスト圧縮](https://code.claude.com/docs/ja/prompt-caching.md#compacting-the-conversation)が行われるまで、[会話とともに保存された](https://code.claude.com/docs/ja/cli-reference.md#system-prompt-flags-in-resumed-conversations)テキストを読み続けます。

変更したテキストは次のターンで Claude に届き、[プロンプトキャッシュ](https://code.claude.com/docs/ja/prompt-caching.md)は最初からやり直しになるため、そのターンは遅くなり、コストも高くなります。このフィールドには Claude Code v2.1.321 以降が必要です。v2.1.299 以降 v2.1.321 より前のバージョンでは、実行中の会話は次のターンで変更後のテキストを受け取っていました。

### コマンドと設定

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/docs/ja/plugins/mods/api#add-a-command) | コマンドが実行される直前 | `{ text }`、`{}`、または `next(e)` |
| `command.describe` | 各コマンドにつき 1 回、コマンド一覧のため | `{ description, argumentHint, isHidden }` |
| `config.set` | `/config` の行が変更される直前 | `next({ ...e, value })` または `{ deny: reason }` |
| `config.describe` | `/config` の各行につき 1 回 | `{ label, description, isHidden }` |
| [`settings.read`](https://code.claude.com/docs/ja/plugins/mods/events#settings-read-hook) | mod が [`$.settings.read`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) を呼び出すとき、または Claude Code がセッションのマージされた設定を構築するとき。Claude Code 自身の読み取り時、および `e.layers` には Claude Code v2.1.304 以降が必要です | `next(e)`、`{ value }`、または `{ deny: reason }` |

#### `settings.read` の `e.layers` と `e.source`

* **`e.layers`**: 設定を保持している使用中のソースごとに 1 つの `{ source, settings }` オブジェクト。[優先順位](https://code.claude.com/docs/ja/settings.md#settings-precedence)の最も低いものが先頭です。[`settings.read` フックが受け取るもの](https://code.claude.com/docs/ja/plugins/mods/events#settings-read-receives)を参照してください。
* **`e.source`**: `$.settings.read({ source: 'policy' })` のように、mod が要求した 1 つのソース。Claude Code 自身の読み取りや、マージされた設定の読み取りでは存在しません

### ターン

ターンイベントは、1 つの回答を開始から終了まで、その中のモデルへの各リクエストも含めて追跡します。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`turn.start`](https://code.claude.com/docs/ja/plugins/mods/events#follow-a-turn) | ターンが始まるとき | `next(e)` |
| [`turn.step`](https://code.claude.com/docs/ja/plugins/mods/events#follow-a-turn) | 1 つのリクエストがモデルに送信される直前 | `yield* next(e)`、または `next({ ...e, model })`、`next({ ...e, effort })` |
| [`turn.complete`](https://code.claude.com/docs/ja/plugins/mods/events#follow-a-turn) | ターンが終了したとき | `next(e)`、または回答の下に 1 行表示するには `{ text }` |

### セッション

セッションイベントは、セッションの開始、終了、コンパクト化、および他のセッションとのメッセージのやり取りを示します。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`session.start`](https://code.claude.com/docs/ja/plugins/mods/api#add-a-command-or-a-tool) | 読み込まれた mod ごとに 1 回、最初のプロンプトの前。その mod の再読み込み後にも再度発火します。`/clear`、`/resume`、`/branch` の後には発火しません。 | `next(e)` |
| `session.end` | セッションが終了するとき、または `/clear`、`/resume`、`/branch` が実行されるとき。`e.reason` は `clear`、`resume`、`logout`、`prompt_input_exit`、`other` のいずれかです。`/branch` は `resume` を報告します。 | `next(e)` |
| `session.compact` | 会話がコンパクト化される直前 | `{ skip: reason }` |
| [`session.receive`](https://code.claude.com/docs/ja/plugins/mods/api#send-and-receive-messages-between-sessions)、[`session.send`](https://code.claude.com/docs/ja/plugins/mods/api#send-and-receive-messages-between-sessions) | 他のエージェントやセッションからメッセージが届いたとき、またはそこへ送信される直前。[セッション間でメッセージを送受信する](https://code.claude.com/docs/ja/plugins/mods/api.md#send-and-receive-messages-between-sessions)を参照してください。 | `receive` では `{ consumed: reason }`、`send` では `{ isDelivered: false, reason }` |
| `session.append` | プロンプト、応答ブロック、ツールの結果、通知など、会話が保持する各行につき 1 回、保存される前 | 行のテキストブロック、または行内の `tool_result` ブロックの `content` を書き換えるには、`message.content` を変更した `next({ ...e, message })` |
| `session.attach`、`session.detach` | 別のアプリがセッションに接続または切断するとき | `next(e)` |
| `session.measure` | 各ターンの後、およびプランの制限の使用率が変化したとき | `next(e)` |

### サブエージェント

サブエージェントイベントは、サブエージェントの種類が Claude に提示されるときと、サブエージェントまたはエージェントチームのチームメイトが起動する直前に発火します。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| `agent.offer` | サブエージェントの種類が Claude に提示されるとき | 提示しないようにするには `{ isOffered: false }` |
| `agent.spawn` | サブエージェントまたは[エージェントチーム](https://code.claude.com/docs/ja/agent-teams.md)のチームメイトが起動する直前、または終了または停止したサブエージェントが再び実行される直前。チームメイトの場合、`e.isTeammate` は `true` です。再開された実行の場合、`e.resume` が設定されます。 | 起動するもののモデルを選択するには `next({ ...e, model })`、または `{ deny: reason }` |

`agent.spawn` フックは、Claude が [`SendMessage`](https://code.claude.com/docs/ja/sub-agents#resume-subagents) ツールでメッセージを送信した場合など、終了または停止したサブエージェントが再び実行される直前にも実行されます。そのイベントでは、`e.resume` は `{ agentId }` です。フックでサブエージェントを数えている場合は、再開されたサブエージェントが重複して数えられないよう、`e.resume` が設定されているイベントをスキップしてください。

再開された実行を拒否するには `{ deny: reason }` を返します。実行は開始されず、サブエージェントは元の状態のままです。`SendMessage` 呼び出しが実行を求めた場合、Claude はその呼び出しの結果として、`a plugin declined the resume:` に続けて指定した理由を読みます。再開された実行について、異なる `model` など変更したイベントを `next` に渡しても、Claude Code はその変更を無視します。

> [!NOTE]
>
> 再開された実行のイベントには Claude Code v2.1.299 以降が必要です。v2.1.299 より前は、サブエージェントが再開されても `agent.spawn` フックは実行されませんでした。それらのバージョンでサブエージェントを再開する `SendMessage` 呼び出しを拒否するには、[`tool.call`](https://code.claude.com/docs/ja/plugins/mods/events#guard-or-change-a-tool-call) フックでそのツールにマッチさせてください。

### インターフェース

インターフェースイベントは、Claude Code が描画箇所を描画するときと、mod が描画したコントロールをユーザーが使用するときに発火します。`ui.render` フックが返すものについては、[インターフェースに描画する](https://code.claude.com/docs/ja/plugins/mods/interface.md)を参照してください。

| イベント | 発火するタイミング |
| :- | :- |
| [`ui.render`](https://code.claude.com/docs/ja/plugins/mods/interface#pick-where-to-draw) | [描画箇所](#render-sites)が描画される直前 |
| `ui.resolve` | mod が読み込まれるとき、アプリ、描画箇所、mod の組み合わせごとに 1 回。結果は、`$.ui.resolve(e)` が読み取る要素テーブルになります。 |
| [`ui.press`](https://code.claude.com/docs/ja/plugins/mods/interface#respond-to-presses-and-typing)、[`ui.input`](https://code.claude.com/docs/ja/plugins/mods/interface#respond-to-presses-and-typing)、[`ui.select`](https://code.claude.com/docs/ja/plugins/mods/interface#respond-to-presses-and-typing) | mod が描画した `Button`、`Input`、`Select` が使用されたとき |
| `ui.focus`、`ui.scroll` | フォーカスされているコントロール、またはペインやバンドのスクロール位置が変わる直前 |
| `ui.close` | ペインが閉じる直前。`e.id` はそのペインで、`e.origin.kind` は `plugin`、`person`、`unload` のいずれかです。 |
| [`ui.message`](https://code.claude.com/docs/ja/plugins/mods/interface#build-a-tree-from-elements) | `Client` 要素が自身の mod にデータを送信するとき |
| [`ui.fault`](https://code.claude.com/docs/ja/plugins/mods/interface#redraw-when-something-changes) | mod が描画した `Client` 要素の読み込み、描画、または実行が失敗したとき。`e.phase` は `load`、`render`、`run` のいずれかで、`e.reason` はエラーメッセージです。Claude Code v2.1.289 以降が必要です。 |

### 他の mod

これらのイベントを使うと、mod は他の mod の読み込み時にその mod を操作し、拒否したり、その mod が受け取る mods API を変更したりできます。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| [`plugin.register`](https://code.claude.com/docs/ja/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | フックモジュールが読み込まれる直前。`e.uses` には、`claude plugin validate` が出力するのと同じ形で、そのモジュールのイベント、mods API 呼び出し、環境変数、状態が列挙されます。各呼び出しは `fs.read` のように `$.` プレフィックスなしで書かれます。 | `{ refuse: reason }` |
| `engine.create` | この mod 用の mods API が構築されているとき | 名前空間を追加した、変更済みの mods API。`user` [ティア](#the-hook-function)以外の mod は、名前空間を除外することもできます。 |

`engine.create` で追加した名前空間のメソッドを他の mod のフックが呼び出すと、そのイベントに対するすべてのフックが戻るまで、メソッドの `$` 呼び出しはそのフックのコンテキストで実行されます。たとえば、相対パスはそのフックの作業ディレクトリを基準に解決され、ターンがそのフックを待っている間は `$.prompt.submit` が拒否されます。それ以降にメソッドが行う呼び出しは、mod 自身のコンテキストで実行されます。

### テレメトリ

テレメトリイベントは、Claude Code がログに記録する使用状況レコードについて発火します。

| イベント | 発火するタイミング | フックが返せる値 |
| :- | :- | :- |
| `telemetry.log`、`telemetry.mark` | テレメトリレコードがログに記録される直前、または機能の 1 回の使用がマークされるとき。インストールする mod では、`on('telemetry.log', { to: 'collector' }, hook)` のように、テレメトリフックにフィルター `{ to: 'collector' }` を指定してください。フィルターがないと、その mod は `claude plugin validate` で不合格になります。`*` はこれらのイベントにマッチしません。 | `next(e)`、または `{ deny: reason }` |

### 設定フックのイベント

各[設定フックのイベント](https://code.claude.com/docs/ja/hooks.md#hook-events)は、`classic.Stop` や `classic.PostToolUse` のように `classic.<Event>` という名前のイベントです。`e` はフックの stdin JSON です。

### mods API 呼び出し

すべての [mods API メソッド](#mods-api-methods)は、`fs.read`、`model.complete`、`ui.open` のように名前空間とメソッドにちなんだ名前のイベントでもあります。これらのイベントのフックは、`next(e)`、`{ deny: reason }`、または `{ value }` を返せます。

これらのイベントの一部は Claude Code 自身のアクションでも発火するため、拒否する前に `next.origin.plugin` が `engine` かどうかを確認してください。

#### Claude Code 自身の `http.fetch` リクエストのフィールド

`http.fetch` フックでは、[`next.origin`](#the-hook-function) が `{ plugin: 'engine', tier: 'core' }` であれば、mod の `$.http.fetch` 呼び出しではなく、モデルリクエストなど Claude Code 自身のリクエストであることを示します。[組み込みガード](https://code.claude.com/docs/ja/plugins/mods/admin.md#know-what-happens-by-default)が読み込まれている場合、mod が[組織の mod として扱われる](https://code.claude.com/docs/ja/plugins/mods/admin.md#install-your-organizations-mods)場合を除き、フックはこれらのイベントを受け取りません。

これらのイベントでは、`e.init` と、`next(e)` が解決される `value` に、特に次のフィールドが含まれることがあります。

| フィールド | 意味 |
| :- | :- |
| `e.init.compress` | フックの後で Claude Code が本文を圧縮する場合に設定されます。`e.init.body` には圧縮前の本文が入っています。本文を圧縮せずに送信するには、`next({ ...e, init: { ...e.init, compress: undefined } })` を呼び出します。 |
| `value.isStreaming` | Claude Code がレスポンス本文を自身で読み取るため `true` に設定され、`value.text` は空になります。代わりに `value.status` と `value.headers` を読み取ってください。独自の `text` で応答するには、`isStreaming` を含まない `value` を返します。 |

これらのイベントとフィールドには Claude Code v2.1.321 以降が必要です。

## mods API メソッド

mods API は、すべてのフックが受け取る `$` 引数です。そのメソッドは `$.ui` などの名前空間にグループ化されています。この表では各名前空間のメソッドを名前で列挙しているため、`$.ui` の行の `open` は `$.ui.open(...)` の呼び出しを意味します。ガイドではよく使うものの使用例を示しており、[お使いのビルド用の型](https://code.claude.com/docs/ja/plugins/mods/create.md#get-the-types-for-your-build)ではすべてのメソッドが例とともに説明されています。

| 名前空間 | メソッド |
| :- | :- |
| `$.plugin` | `name`、`root`：このプラグインの名前とディレクトリ |
| [`$.ui`](https://code.claude.com/docs/ja/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/ja/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` には Claude Code v2.1.300 以降、`place` には v2.1.314 以降が必要です。 |
| [`$.theme`](https://code.claude.com/docs/ja/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：Desktop アプリまたはモバイルアプリが描画する背景を設定し、その背景を取り除きます。Claude Code v2.1.319 以降が必要です。 |
| [`$.command`](https://code.claude.com/docs/ja/plugins/mods/api#add-a-command) | `register`、`run`、`list` |
| [`$.tool`](https://code.claude.com/docs/ja/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list`。`call` が人による承認を必要とする場合（フックや組織が `ask` で応答する呼び出しなど）、`{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }` で解決されます。`<tool>` はツールの名前です。 |
| `$.agent` | `register`、`spawn`、`list`。`list()` はこのセッションのサブエージェントとチームメイトを返します。それぞれに `pending`、`running`、`waiting`、`idle`、`completed`、`failed`、`killed` のいずれかの `status` があり、`idle` と `waiting` には Claude Code v2.1.289 以降が必要です。 |
| [`$.model`](https://code.claude.com/docs/ja/plugins/mods/api#call-a-model) | `complete`、`fork`、`classify` |
| [`$.prompt`](https://code.claude.com/docs/ja/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude は、`submit({ text })` のテキストを、その mod を送信者として示す文の後に読みます。`submit({ text, asUser: true })` は、その文なしで、テキストをユーザー自身の言葉として送信します。 |
| `$.turn` | `abort` |
| [`$.session`](https://code.claude.com/docs/ja/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`、`cwd`、`root`、`model`、`turns`、`id`、`repo`、`surfaces`、`usage`、`version`、`compact`、`send`、`append`、`authorize`。`usage()` は `{ startedAt, context, rateLimits, cost }` を返します：`context` には `tokens`、`window`、`percent` があり、`rateLimits` は `{ kind, percentUsed, resetsAt }` のリストです。 |
| `$.config` | `list`、`set` |
| [`$.settings`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `get`、`set` |
| [`$.fs`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `read`、`write`、`list`、`exists`、`stat`、`ancestors`。`write` はアトミックではありません：ファイルの内容をその場で置き換えるため、別のプロセスが書き込み途中のファイルを読む可能性があります。複数のセッションが変更するデータは `$.store` に保存してください。 |
| [`$.store`](https://code.claude.com/docs/ja/plugins/mods/interface#keep-state) | `get`、`set`、`delete`、`keys`。マシン上のすべてのセッションが共有するキーバリューストアです。[複数のセッションから保存する](https://code.claude.com/docs/ja/plugins/mods/interface.md#save-from-more-than-one-session)を参照してください。 |
| [`$.state`](https://code.claude.com/docs/ja/plugins/mods/interface#keep-a-value-in-\$-state) | リアクティブな状態：`get`、`set`。ヘルパーの `atom`、`read`、`update`、`derive`、`memberOf` は `claude-code` からインポートします |
| [`$.clock`](https://code.claude.com/docs/ja/plugins/mods/api#run-work-in-the-background) | `now`、`sleep`、`after`、`every` |
| [`$.http`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `run`、`spawn` |
| [`$.mcp`](https://code.claude.com/docs/ja/plugins/mods/api#reach-files-processes-and-the-network) | `call`、`connect`。`connect(server)` は、自身のプラグインのマニフェストに記載されている MCP サーバーに接続します。 |
| `$.audio` | `play`、`speak` |
| `$.telemetry` | `log`、`mark`。レコードが送信されるのは、Claude Code または組み込みの mod が呼び出した場合だけです。 |

## 描画箇所

描画箇所は、Claude Code のインターフェースにおける拡張ポイントです。各行は `ui.render` フックにおける `e.component` の値で、`e.props` のフィールドと、それを描画するアプリを示しています。`e.surface` は描画しているアプリの名前で、`terminal`、`desktop`、`vscode` などです。各描画箇所でフックができることは、[Claude Code がすでに描画しているものを変更する](https://code.claude.com/docs/ja/plugins/mods/interface.md#change-what-claude-code-already-draws)で、選択肢ごとの例とともに説明しています。

VS Code 拡張機能での描画には、拡張機能のバージョン 2.1.299 以降が必要です。[機能フラグを取得しない](https://code.claude.com/docs/ja/env-vars.md#features-that-need-feature-flag-fetching)セッションでは、2.1.304 以降が必要です。拡張機能で描画が異なる点については、[VS Code 拡張機能で描画する](https://code.claude.com/docs/ja/plugins/mods/interface.md#draw-in-the-vs-code-extension)に一覧があります。

| 描画箇所 | `e.props` | `e.requestId` | 描画されるアプリ |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/ja/plugins/mods/interface#pick-where-to-draw) | `title`、`isFocused`、`bodyColumns`、`placement`、`scroll`、`view` | ペインの `id` | Terminal、Desktop、VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/ja/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`、[`isCollapsed`](https://code.claude.com/docs/ja/plugins/mods/interface#when-the-user-collapses-the-band)、`isWorking`、`maxRows`、`bodyColumns`、`scroll`、`view` | 1 つのインスタンス | Terminal、Desktop |
| `AbovePromptList`（`AbovePrompt` の行のスタック） | `rows`（各 mod の行ごとに 1 つの `{ plugin, tree }` を含むリスト）と `AbovePrompt` の props | 1 つのインスタンス | Terminal、Desktop。Claude Code v2.1.323 以降が必要です。 |
| [`Placed`](https://code.claude.com/docs/ja/plugins/mods/interface#place-a-row-in-the-transcript) | `id`、`plugin`、`onScreen` | `$.ui.place` が返した `requestId` | Terminal |
| [`Backdrop`](https://code.claude.com/docs/ja/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。v2.1.323 より前は、`scene` は `id`、`overrideColorScheme` は `colorScheme` でした。 | `backdrop` | `desktop` および `mobile` サーフェス。Desktop アプリまたはモバイルアプリが背景の描画を要求したときに、フックが実行されます。 |
| `UserMessage` | `text`、`origin`、`isExpanded`、および origin に応じて `task` または `from` | 描画された行の ID | Terminal、Desktop、VS Code |
| `AssistantMessage` | 返信のテキスト | 描画された行の ID | Terminal、Desktop、VS Code |
| `ToolUse`、`ToolResult`、`ToolGroup` | ツールの名前、入力、結果 | ツール呼び出し ID | Terminal、Desktop、VS Code |
| `CommandOutput` | `command`、`text` | 描画された行の ID | Terminal、Desktop |
| [`AskUserQuestion`](https://code.claude.com/docs/ja/plugins/mods/interface#change-what-claude-code-already-draws) | 質問と選択肢 | ツール呼び出し ID | Terminal、Desktop、VS Code |
| `ToolProgress` | `kind` | ツール呼び出し ID | Terminal |
| [`Spinner`](https://code.claude.com/docs/ja/plugins/mods/interface#change-what-claude-code-already-draws) | `word`、`message`、`suffix`、`mode` | エージェント ID | Terminal、Desktop、VS Code |
| `TurnDuration` | `word`、`durationMs` | 描画された行の ID | Terminal |
| `InfoNotice` | `text`、`command` | 先頭に `notice:` を付けた通知の `text` | Terminal |
| `SessionMode` | `modes` | 1 つのインスタンス | Terminal、Desktop |
| `PromptHint` | `isDraft`、`isWorking`、`hint` | 1 つのインスタンス | Terminal、Desktop |

`e.viewport` には `columns`、`rows`、`isFullscreen` が入っています。ターミナルと Desktop アプリでは、アプリがウィンドウを計測するまでは存在しません。また、これらのアプリでは、その `rows` はウィンドウ全体の高さであり、ペインの高さではありません。VS Code 拡張機能では常に存在します。

ツリーを描画箇所に合わせるには、フック内で次の props を読み取ります。

* **`Pane` またはバンドの幅**：`e.props.bodyColumns` に合わせて描画します
* **トランスクリプトの横にある `Pane` の高さ**：`e.props.placement` が `'dock'` の場合、`e.props.scroll.bodyRows` がペインでツリーに使える行数です
* **プロンプトの上にある `Pane` の高さ**：`e.props.placement` が `'inline'` の場合、ペインはツリーに合わせて上限まで大きくなり、`bodyRows` はその上限です。[`$.ui.open` の `rows` フィールド](https://code.claude.com/docs/ja/plugins/mods/interface#open-a-pane-at-the-right-time)で別の上限を指定できます。

ペインより高いツリーは、全体としてスクロールします。

## 要素

要素は `ui.render` フックが返すツリーの構成要素で、`$.ui.resolve(e)` から取得します。[要素からツリーを構築する](https://code.claude.com/docs/ja/plugins/mods/interface.md#build-a-tree-from-elements)ではよく使う要素をターミナルでの描画例とともに紹介しており、[インターフェースギャラリー](https://code.claude.com/docs/ja/plugins/mods/gallery.md)にはほとんどの要素のスクリーンショットがあります。チェックマークは、そのアプリが要素を描画できることを示します。

| 要素 | 主な props | Terminal | Desktop | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](https://code.claude.com/docs/ja/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex レイアウト、[`gap`、`padding`、`margin`](#box-spacing-steps)、`width`、`height`、`minWidth`、`minHeight`、[`borderStyle`](#box-border-styles)、`borderColor`、`borderDimColor`、`backgroundColor`、`position`、`top`、`left`、`right`、`bottom`、`overflow`、`display`、`hover` | ✓ | ✓ | ✓ |
| [`Text`](https://code.claude.com/docs/ja/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、[`bold`](#text-bold)、`italic`、`underline`、`strikethrough`、`dimColor`、`inverse`、`wrap`、[`size`、`weight`、`mono`、`tabular`](#text-typography)、`hover` | ✓ | ✓ | ✓ |
| [`Button`](https://code.claude.com/docs/ja/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`children`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action`、`variant`、`role`、`hover` | ✓ | ✓ | ✓ |
| [`Link`](https://code.claude.com/docs/ja/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。[制限](#limits)を参照してください。 | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/ja/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](https://code.claude.com/docs/ja/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、[`rows`](https://code.claude.com/docs/ja/plugins/mods/gallery#input)、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | SVG マークアップの `source`（最大 131,072 文字）、`alt` テキスト、`width`、`height`、`isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/ja/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key`、`props`、`width`、`height`、`flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/docs/ja/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`、`columns`（最大 512）、`rows`（最大 256）、`cells`。[色付きセルのグリッドを描画する](https://code.claude.com/docs/ja/plugins/mods/interface.md#draw-a-grid-of-colored-cells)を参照してください。 | ✓ | | |
| `Image` | `key`、最大 2 MiB の PNG や RGBA バイトなどの `source` またはファイルパス、`columns` と `rows`（いずれも最大 255）、`alt` テキスト。[描画できるターミナル](https://code.claude.com/docs/ja/plugins/mods/gallery.md#image-and-client)を参照してください。 | ✓ | | |

`Button` のその他のルール：

* **`action`**：Claude Code 独自の[キーボードショートカットのアクション](https://code.claude.com/docs/ja/keybindings.md)の 1 つを指定し、そのアクションに対するユーザーの割り当てがコードまたは修飾キー付きのキーである場合、その割り当てでボタンが押されます
* **バンド上の数字ホットキー**：バンド内のボタンに数字の `hotkey` を指定すると、ユーザーが空のプロンプトにその数字だけを入力して手を止めたときにも発火します
* **折りたたまれたバンド**：バンドが[折りたたまれている](https://code.claude.com/docs/ja/plugins/mods/interface.md#when-the-user-collapses-the-band)間は、`action` の割り当てもホットキーもバンド内のボタンを押しません
* **1 つのホットキーに 2 つのボタン**：1 つの描画内で 2 つのボタンが同じ `hotkey` を指定した場合は、後のボタンが優先されます。別の mod のボタンが同じキーを使う場合については、[ホットキーが機能しない](https://code.claude.com/docs/ja/plugins/mods/troubleshoot.md#hotkeys-do-nothing)を参照してください。
* **`variant`**：`primary` または `secondary` を指定し、それ以外の値はエラーをスローします。ターミナルでは、`primary` のボタンは `plain` でない限りアクセントカラーで描画されます。
* **`role`**：`dismiss` は閉じるボタンであることを示し、それ以外の値はエラーをスローします。閉じる処理は `onPress` で行ってください。テキストとボタンの行を含むバンドでは、Desktop アプリはその行の最初の `dismiss` ボタンを独自の閉じるコントロールとして描画することがあります。ターミナルは `role` がない場合と同じようにボタンを描画します。

`Button` は `label` の代わりに `children` を持つことができます。

* **子要素として使えるもの**：文字列と `Text` 要素です。たとえば、名前の後に薄い色の詳細を続けたものや、色付きのチップなどです。Claude Code は `Button` 内のそれ以外の要素を拒否します。
* **ボタンの名前**：`label` はボタンの名前であり、デフォルトでは子要素のテキストになります。子要素が 1 つの文字列以外のボタンには、`key` または `label` を指定してください。
* **ターミナルの場合**：子要素はラベルが表示される位置に描画され、そのどこを押しても 1 回の押下として扱われるため、リストの各行を 1 つのボタンにできます
* **Desktop アプリと VS Code 拡張機能の場合**：ボタンは `label` を描画します

> [!NOTE]
>
> 子要素が 1 つの文字列以外の `Button` には、Claude Code v2.1.295 以降が必要です。

`autoFocus` はどのコントロールでも `true` しか受け付けないため、オフにするには props を省略してください。

VS Code 拡張機能は一部の要素の props を無視し、それらを省略した場合と同じように要素を描画します。

* **`Box`**：`position` とその `top`、`left`、`right`、`bottom`、`alignSelf`、`borderDimColor`、`hover`
* **`Text`**：`size`、`mono`、`tabular`、`hover`
* **`Button`**：`hotkey`、`plain`、`autoFocus`、`action`、`hover`。そのため VS Code では、ユーザーはクリックするか、ボタンにフォーカスがある状態で Enter キーを押してボタンを押します。拡張機能は `variant` と `role` も無視します。
* **`Code`**：`language`、`path`、`startLine`、`format`、`wrap`。そのため、コードは色や行番号なしで描画され、`format: 'diff'` のブロックは差分の生のテキストを表示します
* **`Input` と `Select`**：`autoFocus`、および `Input` の `rows`
* **`Svg`**：`isInteractive`

### `Box` の枠線スタイル

`Box` の周囲に枠線を描画するには、`borderStyle: 'round'` のように、`borderStyle` に次のいずれかの名前を設定します。各行には、その名前でターミナルが描画する内容と、枠線の上辺を示しています。

| `borderStyle` | ターミナルが描画する内容 | 上辺 |
| :- | :- | :- |
| `'single'` | 角が直角の細い線 | `┌──┐` |
| `'double'` | 二重線 | `╔══╗` |
| `'round'` | 角が丸い細い線 | `╭──╮` |
| `'bold'` | 太い線 | `┏━━┓` |
| `'singleDouble'` | 上下が細い線、左右が二重線 | `╓──╖` |
| `'doubleSingle'` | 上下が二重線、左右が細い線 | `╒══╕` |
| `'classic'` | ASCII 文字の `+`、`-`、`\|` | `+--+` |
| `'arrow'` | `Box` の内側を指す矢印 | `↘↓↓↙` |
| `'dashed'` | 角が空白の破線 | `╌╌` |
| `'quote'` | 左側に沿ったバー（`▎`）と、残りの 3 辺の空白セル | 空白 |

`borderStyle` に `'rounded'` など、これら以外の名前を指定した `Box` は枠線なしで描画されます。

### `Box` の間隔ステップ

`Box` の間隔 props は `gap`、`columnGap`、`rowGap`、`padding`、`margin`、および `paddingX` や `marginTop` のような `padding` と `margin` の片側・片軸の形式です。それぞれ `gap: 1` のようなターミナルのセル数、または `gap: 'md'` のようなステップ名を受け取ります。ターミナルと VS Code 拡張機能では、各ステップは次のセル数になります。

| ステップ | 横方向のセル数 | 縦方向のセル数 |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

`gap`、`padding`、`margin` にステップを設定すると、そのステップは横方向と縦方向の両方に同時に適用されます。たとえばターミナルと VS Code 拡張機能では、`padding: 'md'` は左右それぞれ 2 セル、上下それぞれ 1 行になります。

ステップ名には Claude Code v2.1.299 以降が必要です。それより前のリリースでは、ステップ名を使用するツリーは描画されません。

### `Text` のタイポグラフィ props

`Text` に `size`、`weight`、`mono`、`tabular` を設定すると、ツリーを描画するアプリに対して、文字サイズ、太さ、等幅書体、または等幅の数字を要求できます。props を利用する前に、ターミナルと VS Code 拡張機能でその props がどう扱われるかを確認してください。設定した props をアプリが無視する場合でも、ツリーはそのアプリで描画され、テキストはその props を省略した場合と同じように表示されます。

| props | 値 | ターミナルでの動作 | VS Code 拡張機能での動作 |
| :- | :- | :- | :- |
| `size` | `'caption'`、`'footnote'`、`'body'`、`'heading'`、`'title'` | 無視されます（ターミナルの文字サイズは 1 種類のみ） | 無視されます |
| `weight` | `'regular'`、`'medium'`、`'semibold'`、`'bold'` | `semibold` と `bold` は太字で描画されます | `semibold` と `bold` は太字で描画されます |
| `mono` | `true` でアプリの等幅書体を要求します | 無視されます（ターミナルは常に等幅） | 無視され、テキストは拡張機能独自の書体のままになります |
| `tabular` | `true` で等幅の数字を要求し、その場で更新される数値や数値の列の位置を揃えます | 無視されます（ターミナルの数字はすでに 1 セル幅） | 無視されます |

これら 4 つの props には Claude Code v2.1.299 以降が必要です。それより前のリリースでは、`size`、`weight`、`mono`、`tabular` を設定したツリーは描画されません。

#### `bold` を `weight` に置き換える

`Text` の `bold` は非推奨となり `weight` が推奨されていますが、引き続き動作します。`weight` を指定していない `Text` で置き換えるには、`bold: true` を `weight: 'semibold'` に変更すると、Claude Code v2.1.299 以降で同じ結果になります。

v2.1.299 より前のリリースでは、`weight` を設定したツリーは描画されません。`Text` に `bold` と `weight` の両方を設定した場合、`bold` は効果を持ちません。

## 制限

フックと mods API 呼び出しは、時間とサイズの制限の下で実行されます。Claude Code は、時間制限を超えたフックをスキップします。入れ子、要素、`Raster` セル、または `Image` のバイト数の制限を超えたツリーは[描画されません](https://code.claude.com/docs/ja/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty)。

| 制限 | 値 |
| :- | :- |
| 1 つのイベントに対するフック自体の実行時間（`next` 内や、`$.clock.sleep` 以外の mods API 呼び出し内の時間は含まない） | 10 秒。`prompt.edit` フックの場合は 50 ミリ秒 |
| `.catch` ハンドラーの実行時間 | 1 秒 |
| すべての `session.end` フックの合計 | [SessionEnd フックの予算](https://code.claude.com/docs/ja/hooks.md#sessionend-input)と同じ長さ。変更しない限り 1.5 秒で、設定の `SessionEnd` フックが終了した時点から計測 |
| `$.process.run` のタイムアウト | デフォルトは 30 秒、最大 10 分 |
| `$.process.run` の `stdout` と `stderr` | それぞれ 4 MiB。切り詰められた場合は `isStdoutTruncated` または `isStderrTruncated` が `true` になります。 |
| `$.model.complete` の `maxTokens` | デフォルトは 1024、最大 64,000 またはモデルの出力上限 |
| `$.fs.read` と `$.fs.write` | 1 ファイルあたり 4 MiB |
| `$.http.fetch` のリクエスト本文 | 4 MiB（文字数で計測）。これより大きい本文での呼び出しは reject されます。 |
| `$.http.fetch` のレスポンス本文 | 4 MiB。`text` には最初の 4 MiB が格納され、残りは読み込まれません。`Content-Length` ヘッダーがそれより大きいサイズを宣言している場合は、代わりに呼び出しが reject され、その理由は `is over the 4194304-byte limit` で終わります。ただし、リダイレクト後の最後のリクエストが `HEAD` メソッドを使用する場合は除きます。`HEAD` の除外には Claude Code v2.1.296 以降が必要です。 |
| 1 回の `$.http.fetch` 呼び出し（リダイレクトと本文を含む） | 30 秒 |
| 1 回の `$.http.fetch` 呼び出しがたどるリダイレクト | 5 回 |
| フックの `drop` の理由、または `config.set` の `deny` の理由 | 4,096 文字。これより長い理由は末尾が切り詰められ、drop または deny はそのまま適用されます。切り詰めには Claude Code v2.1.292 以降が必要で、それより前のバージョンではフックが代わりに[失敗](https://code.claude.com/docs/ja/plugins/mods/events.md#handle-a-hook-that-fails)します。 |
| 1 つのツリー内のテキスト | 最初の 100,000 文字が描画されます |
| `Code` の `language` または `path`、`Select` オプションの `value`、または `Client` の `module` | 10,000 文字。これより長い場合、それを返した `ui.render` フックは[失敗](https://code.claude.com/docs/ja/plugins/mods/events.md#handle-a-hook-that-fails)します。 |
| `Link` の `href` | 2,048 文字。これより長い場合、それを返した `ui.render` フックは[失敗](https://code.claude.com/docs/ja/plugins/mods/events.md#handle-a-hook-that-fails)します。 |
| 1 つのツリーの入れ子の深さ | ルート要素の下に 32 レベル |
| 1 つのツリー内の要素とテキストの子 | 20,000 |
| 1 つのツリー内の `Raster` セル（各 `Raster` の `columns` × `rows`） | 262,144 |
| プロンプトの上に積み重ねられた行 | 要素、`Raster` セル、`Image` のバイト数は行全体で合算され、1 つのツリーの制限に対して計測されます |
| 1 つのツリー内のすべての `Image` の PNG または RGBA のバイト数 | 2 MiB |
| `$.store` | JSON の合計で 4 MiB |
| `$.session.messages()` | 最新の 4,096 エントリ |
| `$.ui.invalidate('ui.render')` による再描画 | 1 秒あたり 10 回に制限。ターミナルでは、表示中のペイン、展開されたバンド、プロンプト下のヒント行については 30 回。それより早い呼び出しはまとめられます。 |
| `$.ui.toast` | `{ timeoutMs }` を渡さない限り 4 秒間表示。[クラシックレンダラー](https://code.claude.com/docs/ja/fullscreen.md#enable-fullscreen-rendering)では、mod の新しいトーストが、表示中または表示待ちの同じ mod の古いトーストに[置き換わる](https://code.claude.com/docs/ja/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear)ことがあります。 |
| ユーザーが求めずに開かれたペイン | ターミナルの幅が 144 列以上で配置。ユーザーが一度開いた後は 110 列以上 |
| 1 つの mod が 1 つの会話内で同時に保持できる `$.ui.place` の行 | 500。上限に達すると、新しい `id` での呼び出しは `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }` に解決されます。 |
| mods API 呼び出しの引数の入れ子の深さ | 28,000 レベル。これを超えると、呼び出しは `nesting deeper than 28000 levels is not supported` で終わるメッセージとともに reject されます。Claude Code v2.1.299 以降が必要です。 |
| `next` に渡す変更済みイベントの入れ子の深さ（`turn.step` のフックなどの[非同期ジェネレーターフック](#events)を除く） | 28,000 レベル。これを超えると、`next` は `nesting deeper than 28000 levels is not supported` で終わるメッセージとともに reject されます。Claude Code v2.1.299 以降が必要です。 |
| フックの戻り値の入れ子の深さ（`ui.render`、`ui.resolve`、非同期ジェネレーターフックを除く） | 28,000 レベル。これを超えると、フックの結果は拒否され、[それを報告する通知](https://code.claude.com/docs/ja/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)に `nesting deeper than 28000 levels is not supported` が含まれます。Claude Code v2.1.299 以降が必要です。 |
| フックモジュールの 1 つのファイル内で互いに入れ子になったスコープ（関数、ブロック、ループなど） | 2,000 |
| コマンド、ツール、サブエージェントの種類、ペインの名前、配置された行の `id`、およびバックドロップの `scene` | 英字、数字、`_`、`-`、最大 64 文字 |
| 1 つの `claude plugin test` テスト | テストが `timeoutMs` を設定しない限り 5 秒 |

## 設定と環境変数

mod に影響する設定と環境変数は次のとおりです。「場所」列には、それぞれがどの設定ファイルまたは環境から読み取られるかを示しています。

| 名前 | 場所 | 動作 |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | 環境、または `~/.claude/settings.json` の `env` | フラグを渡せないアプリ向けに、`--plugin-dir` と同様に読み込むプラグインディレクトリ。`:`（Windows では `;`）で区切った絶対パスです。 |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 環境 | 保存時に mod を再読み込みするかどうか。デフォルトと値については[環境変数リファレンス](https://code.claude.com/docs/ja/env-vars.md)を参照してください |
| `prependPlugins`、`appendPlugins` | 管理設定。ユーザー設定は、管理設定も [`managed-mcp.json`](https://code.claude.com/docs/ja/managed-mcp#deploy-managed-mcp-json) ファイルもないマシンで、認証情報が Team または Enterprise の `/login` ではないセッションの場合に限ります。 | `acme-guard@acme-tools` などのプラグイン ID のリスト。`prependPlugins` の mod はユーザーがインストールしたすべての mod の前に、`appendPlugins` の mod は後に、記載された順序で実行されます。[mod が実行される順序](https://code.claude.com/docs/ja/plugins/mods/events.md#the-order-mods-run-in)を参照してください。 |
| `allowManagedModsOnly` | 管理設定（[組み込みガードのオプション](https://code.claude.com/docs/ja/plugins/mods/admin.md#set-options-on-the-built-in-guard)として） | [組織のものとみなされる](https://code.claude.com/docs/ja/plugins/mods/admin.md#install-your-organizations-mods) mod と、Claude Code に組み込まれた mod だけがフックを実行します。ユーザーの設定フックは引き続き実行されます。 |
| `allowModsToOverrideDenyRules` | 管理設定（[組み込みガードのオプション](https://code.claude.com/docs/ja/plugins/mods/admin.md#set-options-on-the-built-in-guard)として） | ユーザーがインストールした mod が、`deny` ルールを含む[デフォルトで維持される結果](https://code.claude.com/docs/ja/permissions.md#precedence-among-rules-hooks-and-mods)の大半を越えて、ツール呼び出しを承認できるようにします |
| `allowManagedHooksOnly` | 管理設定 | 組織のものではないフックとインストール済みの mod をブロックします。[引き続き実行されるもの](https://code.claude.com/docs/ja/settings-reference.md#what-runs-under-allowmanagedhooksonly)を参照してください。 |
| `disableAllHooks` | 任意の設定ファイル | 管理設定では、インストール済みプラグインの mod やフックは一切実行されません。ユーザー自身の設定では、組織が管理するものは引き続き実行されます。[`disableAllHooks`](https://code.claude.com/docs/ja/settings-reference#disableallhooks) を参照してください。 |
| `disableSideloadFlags` | 管理設定 | 起動時に `--plugin-dir` と `--plugin-url` を拒否します |
| `pluginConfigs` | ユーザー設定または管理設定 | mod の `userConfig` 値を保持します。キーは `acme-guard@acme-tools` などのプラグイン ID で、`--plugin-dir` で読み込んだ mod の場合は `first-mod@inline` のように名前と `@inline` です |

`sec-default@builtin` は Claude Code に組み込まれたガードで、`/plugin` とデバッグログには `cc-plugin-sec-default` として表示されます。[読み込まれる場合](https://code.claude.com/docs/ja/plugins/mods/admin.md#know-what-happens-by-default)、ユーザーがインストールするすべての mod より先に実行されます。管理設定の `prependPlugins` が設定されている場合、このガードはそのリストに記載されているときにだけ、記載された位置で読み込まれます。

ソースは [Claude Code リポジトリの `mods/sec-default` ディレクトリ](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)にあります。

## コマンド

以下のコマンドとフラグで、mod の読み込み、検査、テストを行います。`claude` コマンドはシェルで、`/` コマンドは Claude Code のプロンプトで実行します。表中の `<directory>` は、`claude plugin validate ./first-mod` のように入力するパスを表します。角括弧は省略可能な引数を示します。

| コマンド | 動作 |
| :- | :- |
| [`/plugin`](https://code.claude.com/docs/ja/plugins/mods/overview#see-which-mods-a-session-loaded) | 組み込みではない mod が読み込まれている場合、タブの下に `1 mod active · first-mod` のような行を表示します |
| [`claude plugin validate <directory>`](https://code.claude.com/docs/ja/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | プラグインのマニフェストとフックモジュールを読み取り、エラー、処理するイベント、行う mods API 呼び出しを報告します。`--strict` は警告をエラーとして扱い、`--json` は機械可読なレポートを出力します。 |
| [`claude plugin test [directory]`](https://code.claude.com/docs/ja/plugins/mods/test#write-a-test) | ディレクトリ（指定しない場合はカレントディレクトリ）の下にある、名前が `.test.ts` または `.test.tsx` で終わるすべてのファイルを実行します。テストが失敗するとステータス 1 で終了します。 |
| [`claude --plugin-dir <directory>`](https://code.claude.com/docs/ja/plugins/mods/create#write-a-mod-yourself) | 1 つのセッションでプラグインディレクトリを読み込み、保存時にそのフックモジュールを再読み込みします。複数読み込むにはフラグを繰り返し指定します。 |
| `/reload-plugins` | 実行時にプラグインを再読み込みします |
