SpyBara
Go Premium

plugins/mods/reference.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 105 additions and 97 deletions.

2026
Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Tue 6 23:59 Wed 7 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59

mod リファレンス

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

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

[!NOTE]

完全なリファレンスは Claude Code の mod 用 TypeScript 宣言で、すべてのイベント、メソッド、要素が例とともに記述されています。GitHub 上のコピーは、インストールしている Claude Code のバージョンより古い場合があります。両者が食い違う場合は、Claude Code がお使いのバージョン用に書き出すコピーを信頼してください。

ファイル

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

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

register は on と options を受け取ります。options には、マニフェストが宣言する userConfig フィールドの値が、デフォルト値を補った状態で入っています。

フック関数

mod は、イベントハンドラーである各フックを register 内で on を呼び出して登録します。on は、イベント名、省略可能な matcher（イベントのフィールドに対するフィルター）、フックを受け取ります（例：on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))）。on は、フックのエラーハンドラーを設定する .catch(handler) メソッドを 1 つだけ持つ登録オブジェクトを返します。

引数 内容
$ mods API：mods API メソッドのすべてのメソッド。各呼び出しは、名前空間、メソッドの順に省略せずに書きます（例：$.fs.read('notes.md')）。
e イベントの入力。深く凍結されたプレーンなデータです。変更するには、コピーを next に渡します。
next(e) ミドルウェアと同様の次のハンドラー。このフックの後のフックを実行し、次に Claude Code の動作を実行します。イベントの結果に解決されます。
next.signal イベントが破棄されたときに中止される AbortSignal
next.origin イベントを発火したものの { plugin, tier }。Claude Code 自身は { plugin: 'engine', tier: 'core' } です。mod の tier は、mod が実行される順序における優先度グループで、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 はエラーのテキストです。イベントがそのフック自身、またはフックの外側にある mod のコードによる mods API 呼び出しの内部から発生したためにフックがスキップされた場合、kind は re-entry になります。re-entry には Claude Code v2.1.292 以降が必要です。
next.error.cause kind が re-entry の場合にのみ設定されます。イベントの発生元である mods API 呼び出しを tool.call または PreToolUse フックが変更した場合、またはその呼び出しによって開始されたエージェントを agent.spawn フックが変更した場合は rewritten です。別の mod が mods API に追加したメソッドがそのイベントを発火した場合は、rewritten にも該当しない限り lent です。lent には Claude Code v2.1.292 以降、rewritten には v2.1.300 以降が必要です。
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 ツールが実行される直前 next(e)、{ deny: reason }、または { result }
tool.check tool.call フックと PreToolUse フックの後、Claude Code がツール呼び出しを実行してよいかを判定するとき。next(e) は、ルール、権限モード、それらのフックが下した判定に解決されます。 next(e) または { decision }（decision には allow、ask、deny のいずれかを設定し、任意で reason を指定できます）
tool.describe 各ツールにつき 1 回、その説明が初めて Claude に送信されるとき。MCP ツールの場合は、Claude がツール検索を通じてそのツールを読み込むときに 2 回目が発火し、e.description には読み込まれたツールについて Claude が読むテキストが設定されます。 { description }（任意で isDeferred を指定でき、true にするとツールをツール検索の背後に置き、false にすると最初から読み込みます）

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

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

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

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

tool.check フックでは、ツールがこの呼び出しを読み取り専用と報告した場合に e.isReadOnly が true になります。それ以外の場合、このフィールドは false ではなく存在しません。この値はツール自身の報告であるため、このフィールドだけに基づいて呼び出しを承認する前に、ツール呼び出しが読み取り専用かどうかを確認するを読んでください。

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

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

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

イベント 発火するタイミング フックが返せる値
prompt.submit プロンプトが送信されるとき 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 システムプロンプトの名前付きセクションごとに 1 回。e.name は prompt.compose におけるそのセクションの id です。 { text }、またはセクションを省くには { text: null }
prompt.context 会話ごとに 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 スキルのテキストが Claude 向けに展開されるとき { text }
attribution.text Claude Code がコミットまたはプルリクエストの帰属テキストを作成するとき { text }

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

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

フィールド 型 内容
e.source string スキルの提供元。エンタープライズ、個人、プロジェクトの場所にあるスキルの場合は、それぞれ policySettings、userSettings、projectSettings です。その他の提供元では、plugin、mcp、syncedSkills、built-in などの語になります。
e.pluginName string e.source が plugin であるスキルの場合、そのプラグインの名前
e.path string スキルの SKILL.md ファイルの絶対パス。コマンドファイルとして書かれたスキルの場合は、その .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 を読みます。それ以外のフィールドを変更したフックは失敗します。

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

コマンドと設定

コマンドと設定のイベントは、コマンドが実行または一覧表示されるとき、および /config の行が表示または変更されるときに発火します。

イベント 発火するタイミング フックが返せる値
command.run コマンドが実行される直前 { text }、{}、または next(e)
command.describe 各コマンドにつき 1 回、コマンド一覧のため { description, argumentHint, isHidden }
config.set /config の行が変更される直前 next({ ...e, value }) または { deny: reason }
config.describe /config の各行につき 1 回 { label, description, isHidden }

ターン

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

イベント 発火するタイミング フックが返せる値
turn.start ターンが始まるとき next(e)
turn.step 1 つのリクエストがモデルに送信される直前 yield* next(e)、または next({ ...e, model })、next({ ...e, effort })
turn.complete ターンが終了したとき next(e)、または回答の下に 1 行表示するには { text }

セッション

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

イベント 発火するタイミング フックが返せる値
session.start 読み込まれた 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、session.send 他のエージェントやセッションからメッセージが届いたとき、またはそこへ送信される直前。セッション間でメッセージを送受信するを参照してください。 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 サブエージェントまたはエージェントチームのチームメイトが起動する直前。チームメイトの場合、e.isTeammate は true です。 モデルを選択するには next({ ...e, model })、または { deny: reason }

Claude が SendMessage ツールでサブエージェントを再開する場合、agent.spawn フックは再度実行されません。サブエージェントを再開する SendMessage 呼び出しを拒否するには、tool.call フックでそのツールにマッチさせてください。

インターフェース

インターフェースイベントは、Claude Code が描画箇所を描画するときと、mod が描画したコントロールをユーザーが使用するときに発火します。ui.render フックが返すものについては、インターフェースに描画するを参照してください。

イベント 発火するタイミング
ui.render 描画箇所が描画される直前
ui.resolve mod が読み込まれるとき、アプリ、描画箇所、mod の組み合わせごとに 1 回。結果は、$.ui.resolve(e) が読み取る要素テーブルになります。
ui.press、ui.input、ui.select mod が描画した Button、Input、Select が使用されたとき
ui.focus、ui.scroll フォーカスされているコントロール、またはペインやバンドのスクロール位置が変わる直前
ui.close ペインが閉じる直前。e.id はそのペインで、e.origin.kind は plugin、person、unload のいずれかです。
ui.message Client 要素が自身の mod にデータを送信するとき
ui.fault mod が描画した Client 要素の読み込み、描画、または実行が失敗したとき。e.phase は load、render、run のいずれかで、e.reason はエラーメッセージです。Claude Code v2.1.289 以降が必要です。

他の mod

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

イベント 発火するタイミング フックが返せる値
plugin.register フックモジュールが読み込まれる直前。e.uses には、claude plugin validate が出力するのと同じ形で、そのモジュールのイベント、mods API 呼び出し、環境変数、状態が列挙されます。各呼び出しは fs.read のように $. プレフィックスなしで書かれます。 { refuse: reason }
engine.create この mod 用の mods API が構築されているとき 名前空間を追加した、変更済みの mods API。user ティア以外の 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 }

設定フックのイベント

各設定フックのイベントは、classic.Stop や classic.PostToolUse のように classic.<Event> という名前のイベントです。e はフックの stdin JSON です。

mods API 呼び出し

すべての mods API メソッドは、fs.read、model.complete、ui.open のように名前空間とメソッドにちなんだ名前のイベントでもあります。これらのフックは、そのフックの後に実行される mod からの呼び出しをインターセプトし、next(e)、{ deny: reason }、または { value } を返せます。

mods API メソッド

mods API は、すべてのフックが受け取る $ 引数です。そのメソッドは $.ui などの名前空間にグループ化されています。この表では各名前空間のメソッドを名前で列挙しているため、$.ui の行の open は $.ui.open(...) の呼び出しを意味します。ガイドではよく使うものの使用例を示しており、お使いのビルド用の型ではすべてのメソッドが例とともに説明されています。

名前空間 メソッド
$.plugin name、root：このプラグインの名前とディレクトリ
$.ui resolve、invalidate、open、close、panes、focus、scroll、toast、notify、status、log、notice、ask、copy、selection、blit
$.command register、run、list
$.tool register、call、check、list
$.agent register、spawn、list。list() はこのセッションのサブエージェントとチームメイトを返します。それぞれに pending、running、waiting、idle、completed、failed、killed のいずれかの status があり、idle と waiting には Claude Code v2.1.289 以降が必要です。
$.model complete、fork、classify
$.prompt submit、read、fill、suggest、compose。Claude は、submit({ text }) のテキストを、その mod を送信者として示す文の後に読みます。submit({ text, asUser: true }) は、その文なしで、テキストをユーザー自身の言葉として送信します。
$.turn abort
$.session 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 read
$.env get、set
$.fs read、write、list、exists、stat、ancestors。write はアトミックではありません：ファイルの内容をその場で置き換えるため、別のプロセスが書き込み途中のファイルを読む可能性があります。複数のセッションが変更するデータは $.store に保存してください。
$.store get、set、delete、keys。マシン上のすべてのセッションが共有するキーバリューストアです。複数のセッションから保存するを参照してください。
$.state リアクティブな状態：get、set。ヘルパーの atom、read、update、derive、memberOf は claude-code からインポートします
$.clock now、sleep、after、every
$.http fetch
$.process run、spawn
$.mcp 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 がすでに描画しているものを変更するで、選択肢ごとの例とともに説明しています。

VS Code 拡張機能での描画には、拡張機能のバージョン 2.1.299 以降が必要です。機能フラグを取得しないセッションでは、2.1.304 以降が必要です。拡張機能で描画が異なる点については、VS Code 拡張機能で描画するに一覧があります。

描画箇所 e.props e.requestId 描画されるアプリ
Pane title、isFocused、bodyColumns、placement、scroll、view ペインの id Terminal、Desktop、VS Code
AbovePrompt hasSurvey、isWorking、maxRows、bodyColumns、scroll、view 1 つのインスタンス Terminal、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 質問と選択肢 ツール呼び出し ID Terminal、Desktop、VS Code
ToolProgress kind ツール呼び出し ID Terminal
Spinner word、message、suffix、mode エージェント ID Terminal、Desktop、VS Code
TurnDuration word、durationMs メッセージ ID Terminal
InfoNotice text、command メッセージ ID 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 フィールドで別の上限を指定できます。

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

要素

要素は ui.render フックが返すツリーの構成要素で、$.ui.resolve(e) から取得します。要素からツリーを構築するではよく使う要素をターミナルでの描画例とともに紹介しており、インターフェースギャラリーにはほとんどの要素のスクリーンショットがあります。チェックマークは、そのアプリが要素を描画できることを示します。

要素 主な props Terminal Desktop VS Code
Box key、flex レイアウト、gap、padding、margin、width、height、minWidth、minHeight、borderStyle、borderColor、borderDimColor、backgroundColor、position、top、left、right、bottom、overflow、display、hover ✓ ✓ ✓
Text color、backgroundColor、bold、italic、underline、strikethrough、dimColor、inverse、wrap、size、weight、mono、tabular、hover ✓ ✓ ✓
Button key、label、onPress、hotkey、plain、dimColor、autoFocus、action、hover ✓ ✓ ✓
Link href、label。制限を参照してください。 ✓ ✓ ✓
Code source、language、path、startLine、format、wrap ✓ ✓ ✓
Markdown text、key、dimColor、onLinkPress、pressableLinks ✓ ✓ ✓
Input key、label、placeholder、value、submitLabel、onSubmit、onInput、autoFocus ✓ ✓ ✓
Select key、label、options、value、onSelect、autoFocus ✓ ✓ ✓
Svg SVG マークアップの source（最大 131,072 文字）、alt テキスト、width、height、isInteractive ✓ ✓
Client module、key、props、width、height、flexGrow ✓ ✓
Raster key、columns（最大 512）、rows（最大 256）、cells。色付きセルのグリッドを描画するを参照してください。 ✓
Image key、最大 2 MiB の PNG や RGBA バイトなどの source またはファイルパス、columns と rows（いずれも最大 255）、alt テキスト。描画できるターミナルを参照してください。 ✓

Button のその他のルール：

  • action：Claude Code 独自のキーボードショートカットのアクションの 1 つを指定し、そのアクションに対するユーザーの割り当てがコードまたは修飾キー付きのキーである場合、その割り当てでボタンが押されます
  • バンド上の数字ホットキー：バンド内のボタンに数字の hotkey を指定すると、ユーザーが空のプロンプトにその数字だけを入力して手を止めたときにも発火します
  • 折りたたまれたバンド：バンドが折りたたまれている間は、action の割り当てもホットキーもバンド内のボタンを押しません
  • 1 つのホットキーに 2 つのボタン：1 つの描画内で 2 つのボタンが同じ hotkey を指定した場合は、後のボタンが優先されます

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 キーを押してボタンを押します
  • Code：language、path、startLine、format、wrap。そのため、コードは色や行番号なしで描画され、format: 'diff' のブロックは差分の生のテキストを表示します
  • Input と Select：autoFocus
  • 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 以降が必要です。それより前のリリースでは、ステップ名を使用するツリーの代わりに、Claude Code が独自バージョンのサイトを描画します。

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 を設定したツリーの代わりに、Claude Code が独自バージョンのサイトを描画します。

bold を weight に置き換える

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

v2.1.299 より前のリリースでは、weight を設定したツリーは描画されず、代わりに Claude Code が独自バージョンのサイトを描画します。Text に bold と weight の両方を設定した場合、bold は効果を持ちません。

制限

フックと mods API 呼び出しは、時間とサイズの制限の下で実行されます。Claude Code は、時間制限を超えたフックをスキップします。

制限 値
1 つのイベントに対するフック自体の実行時間（next 内や、$.clock.sleep 以外の mods API 呼び出し内の時間は含まない） 10 秒。prompt.edit フックの場合は 50 ミリ秒
.catch ハンドラーの実行時間 1 秒
すべての session.end フックの合計 SessionEnd フックの予算と同じ長さ。変更しない限り 1.5 秒で、設定の SessionEnd フックが終了した時点から計測
$.process.run のタイムアウト デフォルトは 30 秒、最大 10 分
$.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 以降が必要で、それより前のバージョンではフックが代わりに失敗します。
1 つのツリー内のテキスト 最初の 100,000 文字が描画されます
Code の language または path、Select オプションの value、または Client の module 10,000 文字。これより長い場合、Claude Code はその箇所を独自の表示で描画します。
Link の href 2,048 文字。これより長い href があると、ツリー全体が描画されません。
$.store JSON の合計で 4 MiB
$.session.messages() 最新の 4,096 エントリ
$.ui.invalidate('ui.render') による再描画 1 秒あたり 10 回に制限。ターミナルでは、表示中のペイン、展開されたバンド、プロンプト下のヒント行については 30 回。それより早い呼び出しはまとめられます。
$.ui.toast { timeoutMs } を渡さない限り 4 秒間表示
ユーザーが求めずに開かれたペイン ターミナルの幅が 144 列以上で配置。ユーザーが一度開いた後は 110 列以上
フックモジュールの 1 つのファイル内で互いに入れ子になったスコープ（関数、ブロック、ループなど） 2,000
コマンド、ツール、サブエージェントの種類、ペインの名前 英字、数字、_、-、最大 64 文字
1 つの claude plugin test テスト テストが timeoutMs を設定しない限り 5 秒

設定と環境変数

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

名前 場所 動作
CLAUDE_CODE_PLUGIN_DIRS 環境、または ~/.claude/settings.json の env フラグを渡せないアプリ向けに、--plugin-dir と同様に読み込むプラグインディレクトリ。:（Windows では ;）で区切った絶対パスです。
CLAUDE_CODE_PLUGIN_DIR_WATCH 環境 1 にすると、長時間実行される非対話型セッションが、保存時に --plugin-dir の mod を再読み込みします
prependPlugins、appendPlugins 管理設定。ユーザー設定は、管理設定のないマシンで、認証情報が Team または Enterprise の /login ではないセッションの場合に限ります。 acme-guard@acme-tools などのプラグイン ID のリスト。prependPlugins の mod はユーザーがインストールしたすべての mod の前に、appendPlugins の mod は後に、記載された順序で実行されます。mod が実行される順序を参照してください。
allowManagedModsOnly 管理設定（組み込みガードのオプションとして） 組織のものとみなされる mod と、Claude Code に組み込まれた mod だけがフックを実行します。ユーザーの設定フックは引き続き実行されます。
allowModsToOverrideDenyRules 管理設定（組み込みガードのオプションとして） ユーザーがインストールした mod が、deny ルールで拒否されるツール呼び出しを承認できるようにします
allowManagedHooksOnly 管理設定 組織のものではないフックとインストール済みの mod をブロックします。引き続き実行されるものを参照してください。
disableAllHooks 任意の設定ファイル 管理設定では、インストール済みプラグインの mod やフックは一切実行されません。ユーザー自身の設定では、組織が管理するものは引き続き実行されます。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 として表示されます。管理設定のあるマシン、または認証情報が Team か Enterprise の /login であるセッションでは、ユーザーがインストールするすべての mod より先に読み込まれます。管理設定の prependPlugins が設定されている場合、このガードはそのリストに記載されているときにだけ、記載された位置で読み込まれます。

ソースは Claude Code リポジトリの mods/sec-default ディレクトリにあります。

コマンド

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

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