プラグインのsettings.jsonで既定のエージェントを配布する

プラグインのsettings.jsonでできること

プラグインのルートにsettings.jsonを置くと、そのプラグインを有効化した時点で適用される既定設定を配布できます。対応しているキーはagentとsubagentStatusLineの2つだけです。

これは~/.claude/settings.jsonや.claude/settings.jsonのようなユーザー・プロジェクト単位のClaude Code設定ファイルとは別物です。プラグイン直下のsettings.jsonは、そのプラグインが持つ設定を配るための専用ファイルで、permissionsのような一般設定は書けません。

agentキーで既定のエージェントを切り替える

agentキーは、プラグインが同梱するサブエージェントをメインスレッドとして起動させるための指定です。指定したエージェントのシステムプロンプト・ツール制限・モデルがそのまま適用されます。

{
  "agent": "security-reviewer"
}

この例では、プラグインのagents/ディレクトリに定義したsecurity-reviewerエージェントが有効化時のメインエージェントになります。「プラグインを入れるとClaude Codeの既定の振る舞いそのものが変わる」という設計を、この1キーだけで実現できます。

通常のサブエージェントは@メンションやTaskツール経由で必要なときだけ呼び出す存在ですが、agentキーで指定したエージェントはメインスレッドそのものとして動きます。プラグインを有効にした瞬間から、ツール制限やシステムプロンプトを含めた振る舞い全体がそのエージェントの定義に従うということです。コードレビュー専用プラグインのように「このプラグインを入れたら常にレビュアーとして振る舞ってほしい」という要望に、ユーザー側の追加設定なしで応えられます。

ただしagentはプラグイン専用のキーではなく、利用者の~/.claude/settings.jsonやプロジェクトの.claude/settings.jsonでも指定できる通常の設定キーです。プラグインが配るのはあくまで既定値で、利用者側の設定や1セッションだけ有効な--agentフラグがあれば、そちらが優先されます。

subagentStatusLineでサブエージェント行の表示を変える

もう1つのキーsubagentStatusLineは、エージェントパネルに並ぶ各サブエージェントの行の表示形式を差し替えます。既定の「名前・説明・トークン数」という行を、独自のフォーマットに置き換えられます。

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

指定したコマンドはリフレッシュのたびに1回実行され、表示中の全サブエージェント行をまとめたJSONを標準入力で受け取ります。入力にはcolumns(行の表示幅)とtasks配列が含まれます。各タスクが持つのはid name type status description label startTime model effort contextWindowSize tokenCount tokenSamples cwdの13項目です。コマンドは{"id": "<task id>", "content": "<行の内容>"}という形式のJSON行を、上書きしたい行の数だけ標準出力に書き出します。idを省略した行は既定表示のままになり、contentを空文字にするとその行を非表示にできます。

たとえばtokenCountをcontextWindowSizeで割れば、そのサブエージェントがどれだけ文脈を使い切っているかを行ごとにパーセント表示できます。effortフィールドを使えば、lowからmaxまでの推論負荷や数値のトークン予算をそのまま行に出すこともできます。既定の表示は名前・説明・トークン数の3項目に固定されているため、チームの運用で優先して見たい指標が違う場合に、この仕組みで置き換える価値が出てきます。

agent / subagentStatusLine以外のキーは無視される

settings.jsonにagentとsubagentStatusLine以外のキーを書いても、静かに無視されるだけでエラーにはなりません。将来のリリースで対応キーが増える可能性はありますが、プラグインから配布できる既定設定はこの2つに限られます。permissionsやhooksのような設定をプラグイン経由で強制したい場合は、settings.jsonではなくuserConfig(有効化時にユーザーへ値の入力を促す仕組み)や、プラグインが同梱するhooks・agentsの定義そのもので実現する設計になります。

plugin.jsonのsettingsキーとの優先順位

plugin.jsonにもsettingsという同名の設定を書けるフィールドがあります。両方を用意した場合、settings.jsonファイルの内容がplugin.json内のsettingsより優先されます。1つのプラグインで設定を二重管理する必要はなく、通常はsettings.jsonファイル側に集約しておくほうが見通しがよくなります。

マニフェスト(plugin.json)はname・version・コンポーネントのパスなどをまとめて管理する場所なので、agentやsubagentStatusLineのような値もそこに一緒に書きたくなる場面はあります。ただし優先順位のルールがある以上、両方に矛盾する値を置くと意図しないほうが勝つ可能性があります。プラグインの規模が大きくなるほど、既定設定はsettings.jsonファイルに寄せておいたほうが、どちらが有効かを毎回考えずに済みます。

agentキーが起動するのは「プラグインのサブエージェント」という制約

agentで指定するのは、あくまでそのプラグインのagents/ディレクトリに定義されたサブエージェントです。プラグイン由来のサブエージェントには、セキュリティ上の理由からhooks・mcpServers・permissionModeのfrontmatterフィールドが効かないという制約があります。プラグインを配布する側は、既定エージェントに複雑な権限制御を持たせたい場合、この制約を先に確認しておく必要があります。どうしても必要なら、そのエージェント定義を.claude/agents/や~/.claude/agents/にコピーして使う形に切り替えます。

第三者が配布するプラグインのエージェントを、そのまま無条件で強い権限のメインスレッドにしてしまわないための制約と見てよいでしょう。agentキーで既定の振る舞いを配れる代わりに、hooksやMCPサーバーのような外部との接続点まではプラグイン単独で握れない、という設計です。権限まわりを緩めたい場合は、利用者側のpermissions.allowにルールを追加する方法もありますが、その場合はセッション全体に適用される点に注意します。

managed settingsとの関わり方が2キーで違う

subagentStatusLineには、通常のstatusLineと同じ信頼ゲート・disableAllHooks・allowManagedHooksOnlyの制約がかかります。ただし1点だけ例外があります。プラグインが配布するsubagentStatusLineは、管理設定のenabledPluginsでそのプラグインが強制的に有効化されている場合でも、allowManagedHooksOnlyの制約を受けません。組織展開でこの挙動を前提に設計しておくと、想定より広い範囲でカスタム表示が有効になる、という驚きを避けられます。

配布前にローカルで確認する

--plugin-dirフラグで自分のプラグインを読み込めば、インストールなしでsettings.jsonの効果を確認できます。

claude --plugin-dir ./my-plugin

agentを指定している場合は、起動直後のメインエージェントが意図したものになっているかをまず確認します。システムプロンプトやツール制限が想定どおり効いているかは、実際にそのエージェントに何か作業を依頼してみるのが確実です。subagentStatusLineを指定している場合は、サブエージェントを実際に動かしてエージェントパネルの行が想定どおりのフォーマットで表示されるかを見ます。

よくあるつまずき

• 一般的な設定もこのファイルに書けると思い込む: agentとsubagentStatusLine以外は無視される。permissionsやhooksを配りたいなら別の仕組みを使う
• plugin.jsonのsettingsとsettings.jsonファイルを両方書いて混乱する: 優先されるのはsettings.jsonファイル。二重管理せず1箇所に集約する
• agentで指定したエージェントにhooksやMCPサーバーを設定したつもりになる: プラグイン由来のサブエージェントではhooks・mcpServers・permissionModeは読み込まれない
• subagentStatusLineのcommandが表示幅を無視する: 入力のcolumnsフィールドを見て出力を切り詰めないと、狭いターミナルで折り返しや崩れが起きる

使い分け早見表

よくある質問

settings.jsonを書かなくてもプラグインは動きますか

動きます。settings.jsonは既定設定を配りたいときだけ追加する任意のファイルで、無くてもプラグインの他のコンポーネントには影響しません。

agentで指定したエージェントが見つからない場合はどうなりますか

agentの値はプラグインのagents/配下にあるエージェント定義のnameと一致させます。--plugin-dirで読み込んで起動し、メインエージェントが意図したものになっているかを確認してから配布します。

ユーザー側で既定エージェントを上書きできますか

agentはプラグイン専用のキーではなく通常の設定キーでもあります。利用者は自分の~/.claude/settings.jsonやプロジェクトの.claude/settings.jsonでagentを指定でき、1セッションだけなら--agentフラグが設定より優先されます。プラグインのsettings.jsonが配るのはあくまで既定値という位置づけです。

subagentStatusLineはhooksが無効化されている環境でも動きますか

通常のstatusLineと同じ信頼ゲート・disableAllHooksの制約を受けるため、hooksを無効化する設定が働いている環境では動きません。allowManagedHooksOnlyについてのみ、プラグインが強制有効化されている場合の例外があります。

userConfigで入力させた値もsettings.jsonに書くのですか

書きません。userConfigで入力させた値は、非機密なら利用者側の~/.claude/settings.jsonにpluginConfigs[<plugin-id>].optionsとして、機密なら対応するOSのキーチェーンに、キーチェーンが無い環境では~/.claude/.credentials.jsonに保存されます。プラグイン直下のsettings.jsonとは保存場所も役割も別物です。前者は「有効化時にユーザーへ入力してもらう値」、後者は「プラグイン開発者があらかじめ決めておく既定値」という違いになります。

まとめ

プラグイン直下のsettings.jsonは、agentとsubagentStatusLineという2つのキーに限定した既定設定の配布手段です。agentはプラグインのサブエージェントをメインスレッドとして起動し、subagentStatusLineはサブエージェント行の表示を独自フォーマットに置き換えます。配布前に確認しておく価値がある制約が2つあります。plugin.json側のsettingsよりsettings.jsonファイルが優先されること、そしてプラグイン由来のサブエージェントにはhooks・mcpServers・permissionModeが効かないことです。permissionsやhooksのような一般設定を配りたい場合は、このファイルの対象外なので別の仕組みを検討します。対応するキーは2つだけですが、Claude Codeの既定の振る舞いを丸ごと変えられる強い設定なので、小さく試してから配布範囲を広げるのが安全です。