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

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

プラグイン直下のsettings.jsonはagentとsubagentStatusLineだけを配布できる既定設定です。plugin.jsonとの優先順位や制約を解説します。

読了目安 約9分

プラグインの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エージェントが、有効化したセッションのメインエージェントになります。メインの会話がそのエージェントのシステムプロンプトとモデルで答えるので、コードレビュー専用プラグインのように「入れたら常にレビュアーとして振る舞う」配布を、利用者の追加設定なしで組めます。

通常のサブエージェントは@メンションやAgentツール経由で必要なときだけ呼び出す存在です。agentキーで指定したエージェントは、メインスレッドそのものとして動きます。agentはプラグイン専用のキーではなく、~/.claude/settings.jsonやプロジェクトの.claude/settings.jsonにも書ける通常の設定です。このキーはclaude agentsから起動するセッションの既定エージェントも決めます。サブエージェント側のfrontmatterにあるomitClaudeMdは、メインのセッションエージェントとして動くときは無視されます。どの値が勝つかは、後述の優先順位で決まります。

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行を、上書きしたい行の数だけ標準出力に書き出します。contentの文字列はそのまま描画されるので、ANSIカラーやOSC 8のハイパーリンクも使えます。idを省略した行は既定表示のままになり、contentを空文字にするとその行を非表示にできます。

たとえばtokenCountをcontextWindowSizeで割れば、サブエージェントがコンテキストをどれだけ使っているかを行ごとにパーセント表示できます。modelとcontextWindowSizeはv2.1.205以降、effortはv2.1.214以降で入ります。モデルが未確定のタスクでは、modelとcontextWindowSizeが省かれます。effortはlow・medium・high・xhigh・maxのいずれかの推論負荷か、数値のトークン予算です。サブエージェントがセッションの設定を引き継ぐ場合は入りません。値は設定されたとおりに載るため、モデルがその水準に対応していなければ、実際に適用される負荷は表示と異なることがあります。

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

settings.jsonにagentとsubagentStatusLine以外のキーを書いても、読み込み時に捨てられるだけでエラーにはなりません。hooksはプラグインのhooks/hooks.jsonで配り、権限は利用者側のsettings.jsonで設定してもらいます。ユーザー固有の値はuserConfig(有効化時にユーザーへ値の入力を促す仕組み)で入力してもらいます。

検証コマンドもこの違いは教えてくれません。次のsettings.jsonを持つプラグインにclaude plugin validateをかけると(v2.1.287)、結果は下のとおりです。

{ "agent": "security-reviewer", "permissions": { "allow": ["Bash(ls)"] } }
claude plugin validate .

出力はmanifestのauthorが無いという警告1件だけで、✔ Validation passed with warnings、終了コード0で終わります。permissionsが捨てられることへの指摘は出ません。--strictを付けると警告が失敗扱いになり、このauthorの警告で終了コード1になります。settings.jsonの中身は、検証コマンドではなく起動して確かめる対象です。

同じキーが複数の場所にあるとき、どの値が勝つか

プラグインの既定値は、設定の層の中でいちばん弱い立場です。値が衝突したときの決まり方は3段あります。

手順

agentの値が決まる順

  1. 1

    利用者の設定が勝つ

    利用者自身の~/.claude/settings.jsonにagentがあれば、プラグインの既定値より優先されます。1セッションだけなら--agentフラグが設定のキーより強く働きます。

  2. 2

    同じプラグイン内ではファイルが勝つ

    plugin.jsonのsettingsとsettings.jsonファイルが両方あり、ファイル側が対応キーを1つでも持つなら、ファイルが使われてplugin.jsonのsettingsは無視されます。ファイルが対応キーを1つも持たない場合は、この規則の対象外です。既定設定をsettings.jsonファイルに寄せておけば、どちらが効いているかを毎回考えずに済みます。

  3. 3

    複数のプラグインでは後から読んだほうが勝つ

    2つのプラグインが同じキーを設定すると、後から読み込まれたプラグインの値が使われます。claude --debugのログにoverrides settingと出ます。

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

agentで指定するのは、あくまでそのプラグインのagents/ディレクトリに定義されたサブエージェントです。プラグイン由来のサブエージェントには、セキュリティ上の理由からhooks・mcpServers・permissionModeのfrontmatterフィールドが効かないという制約があります。hooksやMCPサーバーが要るなら、そのエージェント定義を.claude/agents/や~/.claude/agents/にコピーして使う形に切り替えます。プラグインの作者であれば、hooksをhooks/hooks.jsonに、MCPサーバーを.mcp.jsonに置く方法もあります。こちらはサブエージェントだけでなく、プラグインが有効な間ずっと適用されます。

agentで指定したエージェントはメインスレッドとして動くので、Agentツールを使って別のサブエージェントを呼び出せます。呼べる種類を絞りたい場合は、そのエージェント定義のtoolsフィールドにAgent(agent_type)の形式で書きます。

権限のルールをpermissions.allowに足す手もありますが、settings.jsonやsettings.local.jsonに書いたルールはセッション全体に効きます。プラグインのサブエージェントだけを緩める使い方にはなりません。

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

subagentStatusLineには、通常のstatusLineと同じ信頼ゲート・disableAllHooks・allowManagedHooksOnlyの制約がかかります。ただしプラグインから届く値は、hooksと扱いが違います。管理設定のenabledPluginsでプラグインを強制有効化していても、allowManagedHooksOnlyが有効な環境ではプラグインのsubagentStatusLineは動きません。表示を組織で揃えたいなら、管理設定側にsubagentStatusLineを書きます。

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

手順

配布前の確認の流れ

  1. 1

    manifestを検証する

    claude plugin validate <path>でplugin.jsonと、ディレクトリ内のスキル・エージェント・コマンドを検証します。上で見たとおりsettings.jsonのキーは検査されないので、これは入口の確認です。

  2. 2

    フォルダから読み込む

    --plugin-dirでフォルダを直接読み込めば、マーケットプレイスなしで効果を確かめられます。

    claude --plugin-dir ./my-plugin
  3. 3

    実際に動かす

    agentを指定したなら、メインエージェントが意図したものかを起動直後に見て、作業を1つ頼んでシステムプロンプトとツール制限の効き方を確かめます。subagentStatusLineは、サブエージェントを動かしてエージェントパネルの行を見ます。

組織が管理設定のdisableSideloadFlagsを有効にしている環境では、--plugin-dirは起動時に拒否されます。その環境ではマーケットプレイス経由で確かめることになります。

よくあるつまずき

  • subagentStatusLineのcommandが表示幅を無視する: 入力のcolumnsフィールドを見て出力を切り詰めないと、狭いターミナルで折り返しや崩れが起きる

使い分け早見表

配りたいもの使う仕組み理由
プラグイン有効化時の既定エージェント使う仕組みsettings.jsonのagent理由1キーでメインスレッドの振る舞いごと切り替えられる
サブエージェント行の独自表示使う仕組みsettings.jsonのsubagentStatusLine理由既定の名前・説明・トークン数表示を置き換えられる
APIエンドポイントやトークンなどユーザー固有の値使う仕組みuserConfig理由有効化時にユーザーへ入力を促す仕組みで、ハードコードを避けられる
permissions・hooksなど一般設定使う仕組みプラグインのhooks定義や利用者側の.claude/settings.json理由プラグイン直下のsettings.jsonでは配布できない

よくある質問

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

書きません。非機密の値は利用者側のsettings.jsonのpluginConfigsに保存され、機密の値はプラットフォームの安全な資格情報ストアに入ります。前者は「有効化時にユーザーへ入力してもらう値」、プラグイン直下のsettings.jsonは「開発者があらかじめ決めておく既定値」で、役割が別です。

まとめ

プラグインで既定のエージェントや表示を配るならsettings.jsonの2キーで足ります。ただし利用者の設定が常に勝つので、配った既定値は「入れた直後の初期値」と考えるのが実態に近くなります。権限やhooksの強制には向かないので、そちらはhooks定義で組み、ユーザー固有の値はuserConfigに任せます。Claude Codeのプラグイン全体の作り方はプラグインとマーケットプレイスの解説にあります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →