サブエージェント

サブエージェント（subagent）は、特定の種類の作業を引き受ける専用の AI アシスタントです。検索結果・ログ・ファイルの中身など、メインの会話に残したくない副次的な作業を独立した文脈で行い、要約だけを返します。同じ種類の作業者に同じ指示を繰り返し渡しているなら、カスタムのサブエージェントとして定義します。

要点#

• 各サブエージェントは独自のコンテキストウィンドウ・システムプロンプト・ツール権限を持つ。リクエストも別に送られ、メインの会話と同じ利用上限に数えられる
• Claude は各サブエージェントの description を見て、いつ任せるかを決める
• 使えるツールを絞り、設定を user 単位で再利用し、軽いモデルへ振り分けて費用を抑えられる
• 定義は Markdown と YAML frontmatter のファイル。自分で書くか、Claude に書かせる
• 会話全体を引き継ぐ「フォーク」も使える
• サブエージェントは1つのセッションの中で動く。多数の独立したセッションを並行して見守るならエージェントビュー、セッション同士でメッセージをやり取りするならセッション間のメッセージ、Claude が組織して監督するセッションの集まりならエージェントチームを使う

組み込みのサブエージェント#

Claude が必要に応じて自動で使います。どれも親の会話の権限ルールを引き継ぎ、多くは制限されたツールセットで動きます。Explore と Plan は、調査を速く安くするため、CLAUDE.md と git status のスナップショットを読み込みません。ほかの組み込みとカスタムのサブエージェントは、定義で omitClaudeMd を設定して CLAUDE.md を省かない限り、両方を読み込みます（読み込まれるものは後述の「起動時に読み込まれるもの」）。

• Explore のモデルはメインの会話のモデルです。メインの会話が Fable のときは接続のしかたで変わります。Claude のサブスクリプション・Anthropic Console アカウント・ANTHROPIC_BASE_URL 経由の LLM ゲートウェイでは、opus エイリアスが指す Opus モデルで動き、Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry・Claude Platform on AWS・Claude apps gateway では、メインの会話のモデルのままです
• Explore という名前の user・project のサブエージェントは組み込みを上書きし、自分の model を保ちます。探索を低コストのモデルで行うには、model: haiku を付けて定義します。Explore を含む全サブエージェントに 1 つのモデルを強制するには、後述の「全サブエージェントを 1 つのモデルで動かす」を見てください
• Explore を呼ぶとき、Claude は徹底度として quick（的を絞った検索）・medium（バランス型）・very thorough（網羅的な分析）を指定します
• Plan は、プランモードで Claude がコードベースを理解したいとき、調査を別の文脈に出し、メインの会話を読み取り専用のまま保ちます
• general-purpose は、探索と変更の両方、結果を解釈する複雑な推論、依存する複数の段階が要る作業に任されます

組み込みは、対話セッションで既定で登録されます。制限するには次の方法があります。

• 特定の組み込みをブロックするには、permissions.deny に入れる（後述「特定のサブエージェントを無効にする」）
• どのサブエージェントにも任せさせないなら、permissions.deny で Agent ツールそのものを拒否する
• 組み込みの Explore と Plan だけを外すには、環境変数 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198 以降）。Claude はそれらに任せず、ファイルを直接読んで探索する
• 非対話モードと Agent SDK では、CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 で全組み込みを外し、自分のものだけを渡せる

general-purpose が無いセッションで、subagent_type を省いた Agent ツール呼び出しは subagent_type is required で失敗します。

最初のサブエージェントを作る#

サブエージェントは、YAML frontmatter つきの Markdown ファイルです。Claude に書かせるか、自分でファイルを書きます。

• /agents を実行すると、Claude に頼むか .claude/agents/ と ~/.claude/agents/ を直接編集するよう促されます
• v2.1.197 以前では、/agents が、動作中のサブエージェントを並べる「Running」タブと、作成・編集・削除の「Library」タブを持つウィザードを開きます

手順の例（ユーザー単位でコードを見直すサブエージェント）：

1. Claude に、作りたいものと保存先を伝えます

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

2. ~/.claude/agents/code-improver.md を開き、frontmatter が頼んだとおりか確かめます

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

3. 試します：「Use the code-improver agent to suggest improvements in this project」。会話の記録には、サブエージェント名と短いタスクの説明の行（code-improver(Suggest code improvements) など）が出ます

• ~/.claude/agents/ に置いたので、このマシンの全プロジェクトで使えます。1つのプロジェクトに限るなら、そのプロジェクトの .claude/agents/ に移します
• Claude が新しいサブエージェントを見つけられないときは、Claude Code を再起動します。これは、セッション開始時に ~/.claude/agents/ が無かった場合に限ります（動作中のセッションは、新しく作られた agents ディレクトリを検知しないため）
• 手書き・CLI のフラグ・プラグインでも配れます

置き場所と優先順位#

ファイルの場所で、誰が使えるかが決まります。同じ名前が複数あるときは、優先度の高い場所のものが使われます。

• プロジェクトのサブエージェント（.claude/agents/）はコードベース固有のもの向けで、バージョン管理に入れてチームで育てられます。現在の作業ディレクトリからリポジトリルートまで遡り、間にあるすべての .claude/agents/ を走査します。入れ子の複数のディレクトリが同じ name を定義していれば、作業ディレクトリに最も近い定義が使われます
• --add-dir や /add-dir で加えたディレクトリの .claude/agents/ も、プロジェクトのサブエージェントと並べて読み込まれます。--add-dir を使わずプロジェクトをまたいで共有するなら、~/.claude/agents/ かプラグインを使います
• ユーザーのサブエージェント（~/.claude/agents/）は、全プロジェクトで使える個人用です
• .claude/agents/ と ~/.claude/agents/ は再帰的に走査されるので、agents/review/ などのサブフォルダに整理できます。識別は frontmatter の name だけで、サブフォルダのパスは呼び出し方に影響しません
• name は全体で一意にします。同じ .claude/agents/（サブフォルダを含む）の中で2つのファイルが同じ名前を宣言すると、片方だけが読み込まれ、どちらかはファイルシステムの読み取り順で決まり、文書化された優先順位はありません。/doctor が、同じディレクトリ内の同名ファイルを報告して、1つを残すよう名前の変更・削除を提案します（v2.1.205 より前は、重複を一覧し有効な定義を示す診断画面が開きました）
• プラグインの agents/ も再帰的に走査されます。ただし user・project と違い、サブフォルダはスコープ付き識別子の一部になります。プラグイン my-plugin の agents/review/security.md は my-plugin:review:security として登録されます

--agents で渡す（CLI 定義）#

起動時に JSON で渡します。そのセッションだけで有効で、ディスクには保存されません。クイックテストや自動化スクリプト向けです。1回の --agents で複数を定義できます。

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Windows PowerShell では、JSON を @' と '@ で囲んだヒアストリングにして claude --agents へ渡します。

• 非対話モードでは、--agents は同じオブジェクトを書いた JSON ファイルのパスも受け付けます（claude -p --agents ./agents.json "Review my changes"）。対話セッションではファイルパスを拒否します。ファイル形式は v2.1.281 以降
• JSON の最上位のキーがエージェント名、値がその定義です。名前を - で始めないでください
• 定義のフィールド：prompt（システムプロンプト。ファイル形式の Markdown 本文に相当。空でもよい。空の prompt で memory も無いエージェントを --agent でセッションのエージェントに選ぶと、セッションのシステムプロンプトは変わらない。空の prompt は v2.1.281 以降）と、frontmatter の description・tools・disallowedTools・model・permissionMode・mcpServers・hooks・maxTurns・skills・initialPrompt・memory・effort・background・omitClaudeMd・isolation
• color と experimental は受け付けられず、エラーにはならず無視されます

管理設定とプラグインのサブエージェント#

• 管理サブエージェント：管理者が、管理設定ディレクトリ内の .claude/agents/ に、プロジェクト・ユーザーと同じ frontmatter 形式の Markdown を置いて配ります。同名の project・user のものより優先されます
• プラグインのサブエージェント：インストールしたプラグインから自動で読み込まれ、@ メンションの補完にスコープ付きの名前で出ます

定義はエージェントチームのチームメイトとしても再利用できます。チームメイトの起動を Claude に頼むときにサブエージェントの種類を指定すると、その定義の一部がチームメイトに適用されます。どのスコープのどの部分が表示モードごとに適用されるかは エージェントチーム を参照してください。

定義ファイルを書く#

設定を YAML の frontmatter に、システムプロンプトを Markdown 本文に書きます。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

• サブエージェントが受け取るのは、この本文のシステムプロンプトと作業ディレクトリなど基本的な環境情報だけです（Claude Code のシステムプロンプトは受け取りません）
• Claude Code は ~/.claude/agents/ と .claude/agents/ を監視します。ファイルの追加・編集（Claude に書かせた場合を含む）は数秒以内に検知され、次の委任から新しい定義が使われ、再起動は要りません
• 再起動が要る場合が3つあります：セッション開始時に存在したディレクトリだけが監視されるので、新しい agents ディレクトリに最初のファイルを作ったとき／--add-dir や /add-dir で加えたディレクトリの .claude/agents/ は監視されないので、そこで追加・編集したとき／--disable-slash-commands で起動したセッションは、これらのディレクトリを一切監視しない
• 非対話モードでは、--append-subagent-system-prompt で、すべてのサブエージェント（入れ子を含む）のシステムプロンプトの末尾に文章を追加できます。ただし会話自身のプロンプトを再利用するフォークは除きます（v2.1.205 以降）。長い場合は、ファイルに保存して --append-subagent-system-prompt-file でパスを渡します（v2.1.261 以降）
• サブエージェントは、メインの会話の現在の作業ディレクトリで始まります。サブエージェント内の cd は、Bash・PowerShell ツールの呼び出し間で持続せず、メインの会話の作業ディレクトリにも影響しません。リポジトリの隔離されたコピーを渡すには、isolation: worktree を設定します

worktree 隔離での実行チェック#

isolation: worktree のサブエージェントは、Bash・PowerShell のコマンドを自分の worktree の中で実行します。作業ディレクトリがメインのチェックアウトに解決されるコマンド（実行中に worktree のディレクトリが削除された場合など）はエラーで失敗します（v2.1.203 より前は、メインのチェックアウトで実行されえました）。

• この作業ディレクトリの確認は、Claude Code を起動したディレクトリを含むリポジトリ全体が対象です。セッション自体がリンクされたworktreeで動いているときは、その worktree のリンク元のメインのチェックアウトも対象になります。v2.1.210 より前は、起動したディレクトリ自体だけが対象でした
• Bash のコマンドは、コマンド自体も次の2つで検査されます：git をメインのチェックアウトへ向け直すコマンドはブロックされる／コマンド文字列からは、実行する git が worktree の中にとどまると確認できないコマンド（実行時にコマンド名を組み立てる場合など）は拒否される
• リダイレクトの手口と形の規則は、worktreeの隔離の説明にあります。PowerShell のコマンドは作業ディレクトリの確認だけです
• Monitor コマンドも、Bash と同じ作業ディレクトリ・コマンド内容の確認を通ります
• メインの会話自体が worktree で隔離されて動いているときは、同じ検査がセッションと、起動するすべてのサブエージェント（isolation: worktree を持たないものを含む）に適用されます

frontmatter の全フィールド#

--- で囲んだ YAML を、ファイルの先頭に書きます。必須は name と description だけです。複数語のフィールド名は maxTurns・disallowedTools のようなキャメルケースで、表のとおりに一致させます。認識できないフィールドは、エラーなしで無視されます。

cacheTtl は、frontmatter の最上位ではなく experimental マップの中に書きます。

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

読み込まれないファイル#

project・user・管理の agents ディレクトリ、または --add-dir で加えたディレクトリのファイルは、frontmatter に次の問題があると、セッションに報告されず読み飛ばされます。

• name が無い：エージェントの横に置いた文書として扱われる
• 開きの --- がファイルの1行目にない：frontmatter が無いファイルとして読まれ、文書扱いになる
• name が - で始まる、または : を含む：読み飛ばされ、デバッグログにエラーが出る
• name があるが description が無い：読み飛ばされ、理由がデバッグログに出る
• YAML が解析できない：フィールドが何も読まれず、読み飛ばされて、解析エラーがデバッグログに出る

デバッグログは --debug で見えます。frontmatter に name が無いか解析できないプラグインのサブエージェントは、ファイル名を名前として読み込まれます。

モデルを選ぶ#

model フィールドで使うモデルを決めます。

• モデルのエイリアス：sonnet・opus・haiku・fable
• 完全なモデル ID：claude-opus-5-5 や claude-sonnet-5 など。--model フラグと同じ値
• inherit：メインの会話と同じモデル

Claude がサブエージェントを呼ぶときは、その呼び出し限りの model パラメータも渡せます。モデルは次の順で決まります。

1. 呼び出しごとの model パラメータ
2. サブエージェント定義の model（inherit ならメインの会話のモデル）
3. 環境変数 CLAUDE_CODE_SUBAGENT_MODEL（モデルのエイリアスか ID のとき）
4. メインの会話のモデル

• 次の2つの場合は、呼び出しパラメータや frontmatter の opus のようなファミリーのエイリアスが、エイリアスが指す版ではなく、メインの会話のモデルに解決されます。（a）メインの会話のモデルがそのファミリーに属する場合：[1m] 接尾辞を含め、メインの会話の正確なモデルで動き、同じ拡張コンテキストウィンドウになります。（b）Anthropic API 以外のプロバイダーで、Claude Code がメインの会話のモデルのファミリーを判別できない場合（Amazon Bedrock の、裏のモデルに解決できていないアプリケーション推論プロファイルの ARN など）：opus のエイリアスだけが対象で、ANTHROPIC_DEFAULT_OPUS_MODEL を設定している場合は、opus がその設定のモデルに解決されるので当てはまりません
• CLAUDE_CODE_SUBAGENT_MODEL のエイリアスは、メインの会話と同じファミリーでも、常にそのエイリアスが指す版に解決されます
• CLAUDE_CODE_SUBAGENT_MODEL だけでは、組み込みの Explore と Plan のモデルは変わりません（変えるには後述の一括指定）
• v2.1.251 より前は CLAUDE_CODE_SUBAGENT_MODEL がこの順の最初で、呼び出しパラメータと frontmatter（model: inherit を含む）の両方を上書きしていました
• 変数を inherit にするのは、未設定と同じです。v2.1.196 より前は、その値でサブエージェントがメインの会話のモデルに固定され、ほかの決め方が無視されていました
• 呼び出しパラメータ・frontmatter・環境変数の値は、組織の availableModels の許可リストと照合されます。ブロックされた値は別のモデルに置き換わります：opus のようなファミリーのエイリアスなら、許可リストが許す、そのファミリーの最新版で動く（v2.1.222 より前は、継承したモデルで動いた）。それ以外の値、その置き換えが働かないプロバイダー、許可リストがそのファミリーのどの版も許さない場合は、継承したモデルで動く。CLAUDE_CODE_SUBAGENT_MODEL を設定していれば、同じ規則で、そのモデルを先に試す。どちらの置き換えでも、対話セッションでは、要求したモデルと実際のモデルを示す警告が出る
• どのモデルで動いているかは /tasks で確認できます。サブエージェントの行にモデル名が出て、定義（またはフォーク元のスキル）が effort を設定していれば effort も出ます（v2.1.242 以降）
• 呼び出しごとの model パラメータは、サブエージェントを再開したりフォローアップを送ったりしたときも保たれます（v2.1.211 より前は、再開すると定義の model かメインの会話のモデルに戻っていた）
• v2.1.198 から、サブエージェントはメインの会話の拡張思考（extended thinking）の設定も継承します（セッションで有効なら有効、無効なら無効）。サブエージェント単位の thinking 設定はありません。v2.1.198 より前は、メインの設定に関係なく無効でした

全サブエージェントを1つのモデルで動かす#

CLAUDE_CODE_SUBAGENT_MODEL は既定値なので、サブエージェントの定義や Claude が渡すモデルのほうが優先されます。全サブエージェント・チームメイト・ワークフローのエージェントに1つのモデルを適用するには、CLAUDE_CODE_SUBAGENT_MODEL_FORCE も 1 にします（v2.1.257 以降）。

• 両方を設定すると、CLAUDE_CODE_SUBAGENT_MODEL のモデルで動く
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE だけだと、メインの会話のモデルで動く。ただし組み込みの Explore は、組み込みサブエージェントの表にある Explore のモデルで動く

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

• 設定が効いたかは、サブエージェントの動作中に /tasks で、その行のモデルを見て確かめる
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE が有効な間は、サブエージェント定義の model が無視され、Claude もサブエージェント起動時にモデルを渡せない。次の2種類は、メインの会話のモデルで動く：フォーク、model: inherit の「サブエージェントで動くスキル」

できることを制御する#

ツールのアクセス・権限モード・条件つきルールで、サブエージェントができることを絞れます。

使えるツール#

サブエージェントは、メインの会話で使える組み込みツールと MCP ツールを継承しますが、2つのフィルターで絞られます。1つ目は、短いリストのツールをすべてのサブエージェントから外します。2つ目は、バックグラウンドで動くサブエージェント（既定）の組み込みツールを減らします。macOS・Linux・WSL では、メインの会話に Glob と Grep が無くても、サブエージェントが受け取ることがあります。フォークは両方のフィルターを通らず、メインの会話の正確なツールプールを受け取ります。

1つ目のフィルターは、tools に書いてあっても次を外します。

2つ目のフィルターは、バックグラウンドで動くサブエージェントに適用されます。Agent と ExitPlanMode は、動く場所にかかわらず1つ目の条件に従います。それ以外では、バックグラウンドのサブエージェントは、MCP ツールはすべて保ちますが、組み込みツールは次のものだけです：Read・Grep・Glob・LSP・Bash・PowerShell・Edit・Write・NotebookEdit・WebFetch・WebSearch・TodoWrite・Skill・ToolSearch・EnterWorktree・ExitWorktree・Monitor・TaskStop・SendMessage・Artifact。SubagentHandback で報告するサブエージェントはそれも使えます。

• 継承か tools に書いたかにかかわらず、ほかの組み込みツールは外れる。同じ定義でも、フォアグラウンドとバックグラウンドで、解決されるツールが変わりうる。tools のリストが何にも解決されなくならない限り、除去でエラーは出ない
• v2.1.280 より前は、バックグラウンドのサブエージェントは LSP を使えなかった
• ListAgents も他の組み込みツールと同じフィルターに従う（フォアグラウンドのサブエージェントは、セッション間メッセージが有効なセッションで継承し、バックグラウンドのものは保たない）
• エージェントチームのチームメイトは、さらに TaskCreate・TaskGet・TaskList・TaskUpdate・CronCreate・CronDelete・CronList を保つ
• Task ツールが無いセッションでは、サブエージェントが別のモデルでも、タスクツールは渡されない。プロセス内のチームメイトはセッションに従い、分割ペインのチームメイトは別の Claude Code プロセスなので、自分のモデルで決まる

tools を許可リスト、disallowedTools を拒否リストとして使います。次の例は、Read・Grep・Glob・Bash だけを許し、ファイルの編集・書き込みも MCP ツールも使えません。

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

次の例は、Write と Edit を除いてツールプールを継承します（Bash・MCP ツールなどは残ります）。

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

• 両方を設定すると、disallowedTools が先に適用され、その後に残りのプールに対して tools が解決される。両方に書いたツールは外れる
• tools のどの項目もツールに解決できないとき（全部がスペルミス、サブエージェントが使えないツールを指しているなど）、通常は起動を拒否し、Agent ツールが解決できなかった項目を名指しするエラーを返す。v2.1.208 より前は、ツール無しで起動し、空や紛らわしい結果になりえた
• 両方のフィールドは、正確なツール名のほか、MCP サーバー単位のパターンも受け付ける：mcp__<server> か mcp__<server>__* で、そのサーバーの全ツールを許可・除去する。disallowedTools の mcp__* は、どのサーバーの MCP ツールもすべて外す

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

指定子つきの disallowedTools（Bash(git push *) など）は、一致するコマンドだけでなくツール全体を外します。Bash を残して特定のコマンドだけをブロックするには、設定の permissions.deny に Bash の拒否ルール（Bash(git push *) など）を足します。このルールはメインの会話とサブエージェントの両方に効きます。

起動できるサブエージェントを制限する#

claude --agent でメインスレッドとして動くエージェントは、Agent ツールでサブエージェントを起動できます。起動できる種類を制限するには、tools に Agent(agent_type) を書きます。

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

• これは許可リストで、worker と researcher だけを起動できる。ほかの種類を起動しようとすると失敗し、エージェントはプロンプトに許可された種類だけを見る。特定のエージェントだけをブロックして残りを許すなら、permissions.deny を使う
• 制限なしにどのサブエージェントも許すには、括弧なしで Agent と書く（tools: Agent, Read, Bash）
• tools から Agent を完全に省くと、そのエージェントは Agent ツールでサブエージェントを起動できない
• Agent(agent_type) の許可リスト構文は、claude --agent でメインスレッドとして動くエージェントにだけ適用される。サブエージェント定義で tools に Agent を書くと、深さ上限が許す限り、そのサブエージェントが自分のサブエージェントを起動できるが、括弧の中の種類リストは無視される

サブエージェントに MCP サーバーを限定する#

mcpServers フィールドで、メインの会話では使えない MCP サーバーへのアクセスをサブエージェントに与えます。ここで定義したインラインのサーバーは、サブエージェントの開始時に接続され、終了時に切断されます。文字列の参照は、親セッションの接続を共有します。mcpServers は、エージェントのファイルが動く2つの文脈（Agent ツールか @ メンションで起動されたサブエージェント、--agent か agent 設定で起動したメインセッション）の両方で有効です。メインセッションの場合、インライン定義は、.mcp.json や設定ファイルのサーバーと並んで起動時に接続されます。

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• インライン定義は .mcp.json のサーバーエントリと同じスキーマで、サーバー名をキーにし、stdio・http・sse・ws の種類に対応する
• MCP サーバーをメインの会話から完全に外し、ツールの説明が文脈を使わないようにするには、.mcp.json でなくここにインラインで定義する。サブエージェントはツールを得て、親の会話は得ない
• メインセッションに効く MCP の制限は、サブエージェントの frontmatter が宣言したサーバーにも及ぶ：--strict-mcp-config と --bare／エンタープライズの管理 MCP 設定／allowedMcpServers と deniedMcpServers のポリシー。ブロックされたサーバーは読み飛ばされ、名前を挙げる警告が出る。管理設定の制限は、定義のされ方に関わらず全サブエージェントに適用される。--strict-mcp-config は、--agents や SDK の agents オプションでインラインに渡したサーバーを絞らない（呼び出し側の明示の入力のため）

インライン MCP サーバーに必要な信頼#

インラインの MCP サーバーの読み込みの条件です。

• プロジェクトの .claude/agents/ や、--add-dir ディレクトリの .claude/agents/ にあるエージェントファイルのインラインサーバーは、そのエージェントファイルのあるフォルダを信頼した後にだけ読み込まれる（v2.1.238 より前は、信頼を確認せずに読み込まれた）。信頼として数えられないのは、親フォルダの信頼と、-p や SDK セッションが設定ファイルのフックに対して自動で得る信頼。信頼するまでは、そのエージェントファイルのインラインサーバーをすべて読み飛ばし、~/.claude.json の projects["<path>"].hasTrustDialogAccepted キーをデバッグログに書く。信頼済みのワークスペースのリポジトリの外にある --add-dir ディレクトリは、自前の信頼エントリが必要
• 信頼を確認せずに読み込まれるのは、すでに設定したサーバーを参照する名前、~/.claude/agents/ のエージェントファイルのインラインサーバー、--agents や SDK の agents オプションで渡したもの、管理設定が供給するもの

権限モード#

permissionMode で、サブエージェントが動く権限モードを選びます。設定ファイルの値を使うので、Manual モードは default です。未設定なら、メインの会話の権限モードを継承します。

メインの会話の権限モードで、設定した値が使われるかが決まります。

• メインの会話が bypassPermissions・acceptEdits・auto モードのとき、サブエージェントは同じモードで動き、設定した permissionMode は無視される。auto モードでは、分類器がサブエージェントのツール呼び出しを、メインの会話のブロック・許可ルールで評価する。サブエージェントが終わると、分類器はその作業と最終報告も、報告が届く前に見直す
• メインの会話が default・dontAsk・plan のときは、bypassPermissions を除き、設定したモードで動く。bypassPermissions を宣言したサブエージェントは、メインの会話のモードを保つ（この例外は v2.1.267 以降）

スキルを事前読み込みする#

skills フィールドで、起動時にスキルの内容をサブエージェントの文脈に注入します。実行中にスキルを探して読み込ませなくても、分野の知識を渡せます。

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

• 列挙した各スキルの全文が、起動時に注入される。このフィールドは事前読み込みするものを決めるだけで、使えるスキルを制限しない。ないと、サブエージェントは実行中も project・user・plugin のスキルを Skill ツールで見つけて呼べる。スキルの呼び出しを完全に防ぐには、tools から Skill を省くか disallowedTools に入れる
• disable-model-invocation: true のスキルは事前読み込みできない（Claude が呼べるスキルと同じ集合から選ぶため）。同梱の /verify も、Claude が自分では実行できないので事前読み込みできない
• 列挙したスキルが無い・組織のポリシーで無効のときは、読み飛ばされ、デバッグログに警告が出る

永続メモリ#

memory フィールドは、会話をまたいで残る永続ディレクトリをサブエージェントに与えます。コードベースのパターン・デバッグの知見・設計判断などを、時間をかけて蓄えられます。

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

サブエージェントのメモリは自動メモリの一部です。autoMemoryEnabled 設定か CLAUDE_CODE_DISABLE_AUTO_MEMORY で自動メモリを切ると、memory フィールドは効かず、メモリの指示もメモリツールのアクセスも無しで起動します。メモリが有効なときは次のとおりです。

• システムプロンプトに、メモリディレクトリの読み書きの指示が入る
• システムプロンプトに、メモリディレクトリの MEMORY.md の先頭 200 行か 25KB（先に来るほう）も入り、それを超える場合は MEMORY.md を整理する指示が付く
• メモリファイルを管理できるよう、Read・Write・Edit ツールが自動で有効になる

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

フックによる条件つきルール#

ツールの使い方をより動的に制御するには、PreToolUse フックで実行前に検証します。ツールの一部の操作を許し、ほかをブロックしたいときに使えます。次の例は、読み取り専用のデータベースクエリだけを許すサブエージェントです。command のスクリプトが、Bash コマンドの実行前に動きます。

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code は、フックの入力を標準入力から JSON で渡します。検証スクリプトはその JSON から Bash コマンドを取り出し、書き込み操作なら終了コード 2 で終了してブロックします（入力の形はフックのリファレンス）。

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

• macOS と Linux では、スクリプトに実行権限を付けます（付けないと、フックは何もブロックせずに失敗する）：chmod +x ./scripts/validate-readonly-query.sh
• 試すには、サブエージェントに UPDATE 文の実行を頼みます。スクリプトが終了コード 2 を返し、コマンドがブロックされ、サブエージェントに Blocked: Only SELECT queries are allowed が見えます
• Windows では、フックのスクリプトを PowerShell で書き、フックのエントリに shell: powershell を足します

特定のサブエージェントを無効にする#

設定の permissions.deny に Agent(subagent-name) の形で入れます（subagent-name はサブエージェントの name）。組み込みにもカスタムにも有効です。

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

CLI の --disallowedTools フラグでも指定できます。

claude --disallowedTools "Agent(Explore)"

サブエージェントのフック#

サブエージェントのライフサイクルで動くフックを、2通りで設定できます。

• サブエージェントの frontmatter：そのサブエージェントが動いている間だけ動くフックを定義する
• settings.json：サブエージェントの中でも発火するセッション全体のフック。PreToolUse・PostToolUse などのツールイベントはサブエージェントのツール呼び出しにも、メインの会話と同じように発火し、SubagentStart・SubagentStop はサブエージェントの開始・終了で発火する

設定ファイル・管理ポリシー設定・プラグインのフックも、すべてサブエージェントの中で動きます。settings.json の PreToolUse フックは、サブエージェントが使う各ツールの前にも動きます。

frontmatter のフック#

サブエージェントの Markdown に直接フックを書きます。そのサブエージェントが有効な間だけ動き、終了時に片付けられます。Agent ツールか @ メンションで起動されたとき、および --agent か agent 設定でメインセッションとして動くとき（settings.json のフックと並んで動く）に発火します。

• プロジェクトのサブエージェントの frontmatter のフックを動かすには、エージェントファイルのあるフォルダの、ワークスペースの信頼ダイアログを承認する。~/.claude/agents/ のユーザー単位や --agents で渡した定義のフックは、この手順なしで動く。信頼済みのワークスペースのリポジトリの外から --add-dir で加えたフォルダは、別に信頼する
• 信頼するまでは、サブエージェント自体は動くが、frontmatter のフックは読み飛ばされ、信頼のしかたを説明するエラーがデバッグログに出る。親フォルダの信頼では足りず、-p のセッションも信頼済みとは数えない（設定ファイルのフックより厳しい規則）。v2.1.218 より前は、信頼していないフォルダ（非対話セッションを含む）の frontmatter のフックも動いた
• 全フックイベントに対応（フックのリファレンス参照）。サブエージェントでよく使うのは次の3つ

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

エージェントがサブエージェントとして呼ばれたとき、frontmatter の Stop フックは自動で SubagentStop イベントに変換されます。

settings.json のサブエージェントイベントのフック#

メインセッションで、サブエージェントのライフサイクルのイベントに反応するフックを settings.json に設定します。

どちらも matcher で特定のエージェントの種類を名前で絞れます。matcher の値は、project・user のサブエージェントでは frontmatter の name、プラグインのサブエージェントでは my-plugin:db-agent のようなスコープ付き識別子です。スコープ付きの名前はコロンを含むので、アンカーなしの正規表現として評価されます。そのエージェントだけに一致させるには ^my-plugin:db-agent$ のように ^ と $ で固定します。

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

サブエージェントを使う#

自動の委任#

Claude は、依頼の内容・サブエージェントの description・現在の文脈から、自動で任せます。積極的に任せさせたいときは、description に「use proactively」のような言い回しを入れます。description は簡潔に保ちます（合計が 15,000 トークンを超えると、起動時に警告が出ますが、すべて読み込まれます）。プラグインに入ったサブエージェントなら、claude plugin eval で、現実的なプロンプトに対する委任の確かさを測れます（プラグインの評価参照）。

明示して呼ぶ#

自動の委任で足りないときは、自分で指定します。単発の提案から、セッション全体の既定まで3段階です。

• 自然言語：プロンプトでサブエージェントの名前を挙げる。任せるかどうかは Claude が決める
• @ メンション：1つのタスクについて、そのサブエージェントが動くことを保証する
• セッション全体：--agent フラグか agent 設定で、セッション全体をそのサブエージェントとして動かす

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@ メンション：@ を入力して、ファイルの @ メンションと同じように補完からサブエージェントを選びます。

@"code-reviewer (agent)" look at the auth changes

メッセージ全体は Claude に届き、Claude が、頼んだ内容に基づいてサブエージェントのタスクのプロンプトを書きます。@ メンションが決めるのは、Claude がどのサブエージェントを呼ぶかで、どのプロンプトを受け取るかではありません。

• 有効なプラグインのサブエージェントは、補完に、my-plugin:code-reviewer のようなスコープ付きの名前（プラグインがサブフォルダに整理していれば my-plugin:review:security）で出る。セッションで動いている名前付きのバックグラウンドのサブエージェントも補完に出て、名前の横に状態が出る
• 補完を使わず手で入力もできる：ローカルのサブエージェントは @agent-<name>、プラグインのものは @agent- に続けてスコープ付きの名前（@agent-my-plugin:code-reviewer）。この形を入力している間、補完にはエージェントでなくファイルの候補が出るが、送信時にエージェントのメンションは解決される

セッション全体をサブエージェントとして動かす：--agent <name> で、メインスレッド自体がそのサブエージェントのツール制限とモデルを引き受けるセッションを始めます。

claude --agent code-reviewer

• エージェントの prompt が空でない限り、カスタムのサブエージェントのシステムプロンプトは、Claude Code の既定のシステムプロンプトを丸ごと置き換える（--system-prompt と同じ）。CLAUDE.md とプロジェクトのメモリは、定義で omitClaudeMd を設定していても、通常のメッセージの流れで読み込まれる
• 起動時のヘッダーに @<name> と出るので、有効なことを確かめられる
• 組み込みにもカスタムにも使え、選択はセッションを再開しても保たれる（ツール制限とモデルが会話とともに復元される）。再開時にエージェントが無くなっていると、既定のツールで続き、そのエージェント名の警告が出る
• プラグインのサブエージェントは、エージェント名だけで見つかる（claude --agent security-reviewer）。複数のプラグインが同名のエージェントを出しているときは、スコープ付きの名前で区別する（claude --agent my-plugin:security-reviewer）。プラグインが agents/ のサブフォルダに置いている場合は、サブフォルダも含める（claude --agent my-plugin:review:security）
• プロジェクトの全セッションの既定にするには、.claude/settings.json に agent を設定する。両方あるときは CLI フラグが優先される

{
  "agent": "code-reviewer"
}

フォアグラウンドとバックグラウンド#

• フォアグラウンド：完了までメインの会話を止める。権限の確認は、出るたびにあなたへ渡される
• バックグラウンド：あなたが作業を続ける間、並行して動く。権限が要るツール呼び出しに来ると、Claude Code はメインセッションに確認を出し、聞いているサブエージェントの名前を示す。承認すれば続き、Esc でそのツール呼び出し1回だけを、サブエージェントを止めずに拒否できる

Claude が Agent ツールで起動するサブエージェントごとに、次のうち最初に当てはまるもので、フォアグラウンドかバックグラウンドかが決まります。

1. プロセス内のエージェントチームのチームメイトが起動したサブエージェントは、フォアグラウンドで動く。定義が background: true のチームメイトのサブエージェントは、エラーで起動を拒否される。フォークモードが無効で、バックグラウンドタスクを切っていない場合は、チームメイトが run_in_background: true を設定したときもエラーで拒否される
2. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS が 1 なら、あらゆるセッションで、フォークモードの有無にかかわらず、フォアグラウンドで動く
3. フォークモードが有効（対話セッションの既定）なら、フォークも通常のサブエージェントも、バックグラウンドで動き、Claude はフォアグラウンドを求められない
4. フォークモードが無効なら、Claude は既定でバックグラウンド、続行する前に結果が要るときはフォアグラウンドで動かす。フォークモードは、-p の非対話モードと Agent SDK では、有効にしない限り無効。結果が要るときでも、特定のサブエージェントをバックグラウンドに保つには、frontmatter の background を true にする

• context: fork のスキルは、フォークモードの有無にかかわらず、スキルの規則に従う
• バックグラウンドのサブエージェントは、会話のフォークと再開されたフォアグラウンドのサブエージェントを除き、フォアグラウンドより小さい組み込みツールセットで動く
• バックグラウンドのサブエージェントは、すべての権限の確認をメインセッションに出す。その1回のツール呼び出しを超えて続く選択（セッションの残りの許可など）で答えると、メインの会話を含むセッション全体にその答えが適用される
• バックグラウンドのサブエージェントは、バックグラウンドの Bash・PowerShell コマンドを、そのターンの終わりより後も動かし続けられる。そのコマンドが終わると、サブエージェントに通知が送られる
• バックグラウンドのサブエージェントの結果は、後のターンに完了通知として Claude へ届く。Claude は、報告する前にその通知を待ち、先に進捗を尋ねられたら、まだ動いていると答える（v2.1.211 より前は、終わっていないバックグラウンドのサブエージェントの結果を報告することがあった）
• 自分で操作するなら、フォークモードが無効のときは Claude にバックグラウンドかフォアグラウンドで動かすよう頼む。実行中のタスクをバックグラウンドへ移すには Ctrl+B
• プロンプト入力の下のサブエージェントパネルの行は、終わり方で消え方が違う。成功して終わると、行はすぐ消え、スクリーンリーダーモード以外では、フッターに /tasks to see subagents が 30 秒出る。その 30 秒の間に /tasks を実行し、サブエージェントで Enter を押すと、記録を開ける。失敗した、または止めたサブエージェントの行は 30 秒残り、早く消すには選んで x を押す。v2.1.232 より前は、成功した場合も失敗と同じく行を 30 秒残し、フッターの案内はなかった
• 完了したバックグラウンドのサブエージェントは、/tasks に、完了の印を付けて実行中の下に並べて、同じ 30 秒間残り、その詳細画面は終了後も開いたままになる。失敗した、または止めたサブエージェントは一覧から消える。v2.1.208 より前は、完了したサブエージェントは終わった瞬間に一覧から消え、詳細画面も閉じていた

サブエージェントの名前#

Claude は、Agent ツール呼び出しに name パラメータを渡して、サブエージェントに名前を付けられます（あなたに聞かずに付けることもあります）。名前を付けると、サブエージェントに宛先ができ、完了後に Claude が名前でメッセージを送ったり再開したりできます。

• エージェントチームが有効な対話セッションでは、Claude がメインの会話から name つきで起動したサブエージェントは、チームメイトとして起動する。ただし、フォーク、または呼び出し自体が isolation を渡している場合を除く。サブエージェントの frontmatter の isolation はこれを防がず、チームメイトはメインセッションの作業ディレクトリで動く

サブエージェントの API エラー#

応答がストリームの途中で途切れ、部分的な応答にテキストがあってもツール呼び出しが無いときは、Claude Code は実行を終えず、サブエージェントに続けるよう促します（対話セッションでも同じ）。この継続を使い切った後に初めて、エラーで実行が終わります。

• 使用上限や繰り返すサーバーエラーなど、API エラーで実行が終わるサブエージェントは、失敗として Claude に報告します。Claude が受け取るものは、動いた場所で変わります
• フォアグラウンド：レート制限・過負荷・サーバーエラーで、すでにテキスト出力があるサブエージェントが途切れたとき、Agent ツールは、その部分的な出力と、「途切れてタスクを終えていない」という注記を返す。何も出さなかった、または出力がツール呼び出しだけだったサブエージェントは、Agent terminated early due to an API error とエラーの詳細で失敗する。v2.1.199 では、ツール呼び出しだけの形で途切れると、途切れた注記だけを含む空の部分結果が返っていた
• バックグラウンド：サブエージェントは失敗の印が付き、終了時に Claude が受け取るメッセージに API エラーとサブエージェントの最後の出力が入るので、途中までの作業は失われない
• フォールバックモデルのチェーン（モデルの設定参照）を設定していて、サブエージェントがチェーンが対象にする失敗（モデルが使えないなど）に当たったときは、リクエストを受け付ける最初のモデルに切り替え、エラーで終わらず作業を続ける
• 原因の API エラーが解消したら、Claude にタスクの再試行か、サブエージェントの再開を頼む

サブエージェントの出力のスキャン#

Claude Code は、Claude が読む前に、各サブエージェントの最終報告をスキャンします。サブエージェントは、あなたが見ていないファイル・Web ページ・コマンド出力を読んでいることがあり、その文章に、メインの会話を狙った指示が含まれうるためです。スキャンは何も削除せず、言い換えもしません。報告に次の2種類の変更が入ることがあります（v2.1.210 以降）。

• バックスラッシュの挿入：<system-reminder> タグや、Human:・Assistant: で始まる行など、Claude Code 自身の出力を真似た文章に、バックスラッシュを挿入し、会話の一部と誤認されず普通のテキストとして読まれるようにする

• マーカー行：報告が <system-reminder> のようなタグを真似ているか、bypassPermissions や --dangerously-skip-permissions などの権限設定に言及しているとき、[harness: subagent output matched instruction-shaped pattern(s): で始まる行を先頭に付ける。権限設定への言及はマーカー行が付くだけで、文章はそのまま

• スキャンは、内容が悪意あるかを判断せず、報告の指示ができることも変えない。報告に導かれて Claude が行うツール呼び出しは、セッションの権限チェックとサンドボックスを通る。サブエージェントが届く範囲を制限する代わりにはならない

• サブエージェントの結果として Claude に戻る報告は、サブエージェントの出力だと示す見出しの下に届く。見出しは、報告内の指示や承認の主張はサブエージェント自身の言葉で、あなたの権限ではないと述べる

• バックグラウンドのサブエージェントの報告は、あなたからのメッセージではなく自動のイベントだと印の付いた、完了通知の中に届く

よくある使い方#

• 大量の出力を出す作業を隔離する：テスト実行・ドキュメントの取得・ログの処理は、文脈を大きく使う。サブエージェントに任せれば、冗長な出力はその文脈に残り、関係する要約だけがメインに戻る。例：「Use a subagent to run the test suite and report only the failing tests with their error messages」
• 並行して調べる：互いに依存しない調査は、複数のサブエージェントを同時に動かせる。例：「Research the authentication, database, and API modules in parallel using separate subagents」。各サブエージェントが独立に調べ、Claude が結果をまとめる
• つなげる：多段階の作業では、サブエージェントを順に使わせる。各サブエージェントが結果を Claude へ返し、Claude が必要な文脈を次へ渡す。例：「Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them」

並行して動き続ける必要がある作業や、1つの文脈に収まらない作業は、別々のセッションで動かし、Claude にセッション間で調べた内容を渡させます（並列作業の選び方、セッション間のメッセージ参照）。

サブエージェントとメインの会話の使い分け#

メインの会話を使う場面：

• 頻繁なやり取りや、繰り返しの洗練が要る
• 計画・実装・テストなど、複数の段階が大きな文脈を共有する
• 小さな、的を絞った変更
• 待ち時間が気になる（フォークでないサブエージェントは、ゼロから始まるので、文脈を集めるのに時間がかかりうる）

サブエージェントを使う場面：

• 冗長な出力が出て、メインの文脈には要らない
• ツールの制限や権限を強制したい
• 作業が自己完結していて、要約を返せばよい

隔離された文脈でなくメインの会話の文脈で動く、再利用できるプロンプトやワークフローがほしいなら、スキルを使います。すでに会話にある内容への質問は、サブエージェントでなく /btw を使います（全文脈が見えるがツールは使えず、答えは履歴に加わらない。詳しくは対話モードの操作）。

入れ子（サブエージェントが起動するサブエージェント）#

既定では、サブエージェントは自分のサブエージェントを、メインの会話の下に最大3層まで起動できます。深さ上限では、フォーク以外のすべてのサブエージェントから Agent ツールが外れるので、上限にいるサブエージェントは委任された作業を自分で行い、1つの要約を返します。上限にいるフォークは、継承したツール一覧に Agent を残しますが、起動せずエラーを返します。

• 入れ子は、委任された作業がそれ自体、並列の小タスクに分かれる場合に向く（指摘ごとに検証用のサブエージェントを出すレビュー担当など）
• 対話セッションでは、最上位のサブエージェントの要約だけがあなたに戻り、途中の出力はメインの会話に出ない。バックグラウンドのサブエージェントを起動したサブエージェントは、終わる前にその結果を待つ。非対話モードと Agent SDK では、起動したサブエージェントは待たないので、起動元の終了後に終わった入れ子のバックグラウンドのサブエージェントは、メインの会話へ報告する
• 上限を変えるには、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH を、メインの会話の下に許す層の数にする。settings.json の次の例は、入れ子を2層までにする。この値なら、サブエージェントは自分の第2層へ任せられ、第2層はそれ以上任せられない。1 で入れ子を無効にする

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

• 入れ子のサブエージェントの設定は、最上位のものと同じで、同じ置き場所から解決される。入れ子が有効でも、1つのサブエージェントに起動させたくない（読み取り専用のレビュー担当など）ときは、その tools から Agent を省くか、disallowedTools に入れる
• ターミナルでは、入れ子のサブエージェントは、プロンプト入力の下のサブエージェントパネルにツリーで出る。パネル内にまだ子孫がいる行には、その数が (+N) と付く。行を開くと、そのサブエージェントの兄弟と直接の子が、main までのパスつきで見える
• 以前の版の既定：v2.1.172〜v2.1.216 は、既定で最大5層まで入れ子にでき、上限は変えられなかった。v2.1.217〜v2.1.218 は、既定が1で、上げない限りサブエージェントは自分のサブエージェントを起動できなかった。v2.1.219 で既定が3になった

同時に動かせる数の上限#

サブエージェントの使用には2つの上限があり、それぞれ別の変数を持ちます。この節の上限は、多すぎるサブエージェントが動いている間、Claude がさらに起動するのを止めます。もう1つの入れ子の深さ上限（前節）は、入れ子の深さを制限します。1セッションで Claude が起動できるサブエージェントの総数に、上限はありません。

• 既定では、セッションで 20 のサブエージェントが動いているとき、Agent ツールで新たに起動すると Concurrent subagent limit reached で失敗し、エラーは Claude に再試行しないよう伝える。動作中の数が上限を下回れば、再び起動できる
• 上限を変えるには、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS を正の整数にする。ultracode が有効なセッションは、この上限が適用されない。v2.1.217 以降
• 上限がブロックするのは、Agent ツールで Claude が起動するサブエージェントだけだが、ほかの実行も同じ枠を使う：/subtask で始めたセッション内のフォークは動作中に枠を1つ使うが、上限にブロックされない／すでに終わったサブエージェントの再開は、上限を確かめず新しい枠を使うので、再開で動作中の数が上限を超えることがある
• ワークフローのエージェントや、エージェントチームのチームメイトのように、ほかの機能が動かすエージェントは、それぞれの上限に従う

コンテキストの管理#

起動時に読み込まれるもの#

各サブエージェントは、新しい独立したコンテキストウィンドウで始まります。会話履歴・すでに呼んだスキル・Claude がすでに読んだファイルは見えません。Claude がタスクを要約した委任メッセージを作り、サブエージェントはそこから作業します。例外は、新規で始まらず親の会話を引き継ぐフォークです。フォークでないサブエージェントの初期のコンテキストは次のとおりです。

• 自分のサブエージェントを、user・project・local の CLAUDE.md なしで起動するには、frontmatter か --agents の JSON に omitClaudeMd: true を設定する
• サブエージェントの結果を読むメインの会話は CLAUDE.md を全部持っているので、ほとんどの規則はサブエージェントまで届かなくてよい。届けたい規則（「vendor/ ディレクトリを無視する」など）は、任せるときに Claude へ渡すプロンプトで繰り返す
• git status を受け取るサブエージェントは変えられない（Explore と Plan だけが読まない）

メインの会話の状態のうち、フォークでないサブエージェントに届かないものがあります。

• 出力スタイル：サブエージェントは自分のシステムプロンプトで動くので、出力スタイルは、フォークを除き、応答に影響しない
• 自動メモリ：メインの会話の自動メモリは読み込まれない。サブエージェント自身の永続メモリには memory フィールドを使う
• コンテキストウィンドウの大きさ：サブエージェントのウィンドウは、親ではなく自分のモデルで決まる。小さいウィンドウのモデルに任せると、そのサブエージェントのウィンドウは小さくなる

サブエージェントを再開する#

サブエージェントを呼ぶたびに、前のものの続きではなく新しいインスタンスができます。既存のサブエージェントの作業を、やり直さず続けるには、Claude に再開を頼みます。再開されたサブエージェントは、過去のツール呼び出し・結果・推論をすべて含む会話履歴を保ち、止まったところから再開します（自分のバックグラウンドのサブエージェントを起動していたなら、動作中に届いたその結果も履歴に含まれる）。

• サブエージェントが完了すると、Claude はそのエージェント ID を受け取る
• 組み込みの Explore と Plan は1回で終わるもので、エージェント ID を返さないので、Claude は再開できない。作業を続けたいときは、general-purpose かカスタムのサブエージェントを使う
• サブエージェントが maxTurns の上限で止まったとき、返る出力に「部分的」の印が付く。エージェント ID を返すサブエージェントでは、結果に、Claude がそのサブエージェントにメッセージを送って止まった所から続けられるという注記も付く
• Claude は、エージェントの ID か名前を to に入れた SendMessage ツールで再開する。SendMessage はエージェントチームが有効でなくても使える（shutdown_request や plan_approval_response のような構造化されたチームプロトコルのメッセージだけがチームを要する）。サブエージェントとチームメイトのほか、セッション間メッセージが有効なセッションでは、同じツールで、このマシンの、またはマシンの外の、ほかの Claude Code セッションにもメッセージを送れる（セッション間のメッセージ参照）

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Claude が SendMessage で完了したサブエージェントにメッセージを送ると、新しい Agent 呼び出しなしで、バックグラウンドで再開する。Claude が TaskStop で止めたサブエージェントも、止めた実行が終了した後なら同じ。再開した実行は、そのサブエージェントが最初に動いたときのツールセットを保ち、元の実行が温めたプロンプトキャッシュを引き続き読める
• SendMessage ツールを持つサブエージェントも、そのメッセージを送れる。対話セッションでは、再開されたエージェントは、メインの会話でなく、再開したサブエージェントへ報告し、そのサブエージェントは自分の作業を終える前に結果を待つ。サブエージェントが、自分が報告する相手（自分の起動元など）にメッセージを送ったときは、結果をリダイレクトせずにそのエージェントを再開する
• 自分で止めたサブエージェント（/tasks の x か SDK の stop_task リクエスト）は、自動では再開されない。Claude がメッセージを送ると、拒否され、エージェントがキャンセルされたと Claude に伝わる
• そのサブエージェントの行がサブエージェントパネルにまだある間は、その記録に入力して自分で再開できる。その後は、Claude のメッセージで再び自動再開できる
• 再開は、同じ ID の下で新しい実行を始めるので、すでに失敗または完了したサブエージェントは、タスク一覧と Agent SDK のタスクイベントで、再び実行中と表示される（v2.1.205 より前は、再開した実行が動いている間も、前の失敗・完了の状態が表示されていた）
• SendMessage は、名前が、会話の中で前に届いたものと同じエージェントを指しているかを確かめる。新しいエージェントがその名前を使うようになった（再起動したバックグラウンドのエージェントが名前を再利用した場合など）と、Claude Code は誤ったエージェントへ届けず送信を拒否し、エラーに、その名前がいま指すエージェントが示されるので、Claude が宛先を取り直せる。前のエージェントがまだ動いている間に届けるには、Claude が、そのエージェントを起動したときに受け取ったエージェント ID で宛てる。この確認は現在の会話の範囲で、/clear でリセットされる
• サブエージェントは、自分を起動したエージェントからのメッセージを、途中の軌道修正を含む通常のタスクの指示として扱い、自分の権限設定の範囲で従う。誰が送っても守られる制限が2つある：どのエージェントからのメッセージも、保留中の権限確認へのあなたの承認とは数えない。どのエージェントのメッセージも、サブエージェントの権限設定・CLAUDE.md・設定を変えられない。承認を与えられるのは、権限システムか、あなた自身のメッセージだけ
• 明示して参照したいときは、Claude にエージェント ID を尋ねるか、~/.claude/projects/{project}/{sessionId}/subagents/ の記録ファイルから探す。記録は agent-{agentId}.jsonl として保存される

サブエージェントの記録は、メインの会話とは独立に残ります。

• メインの会話のコンパクション：メインの会話がコンパクトされても、サブエージェントの記録には影響しない（別のファイルに保存される）
• セッションの永続性：記録はそのセッション内で残る。同じセッションを再開すれば、Claude Code の再起動後もサブエージェントを再開できる
• 自動削除：cleanupPeriodDays の保持期間（既定 30 日）の後に削除される（保持の掃除の規則に従う）

自動コンパクション#

サブエージェントも、メインの会話と同じ論理で自動コンパクションされます。同じ条件で起動し、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE もサブエージェントに適用されます。コンパクションのイベントは、サブエージェントの記録ファイルに記録されます。

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

preTokens は、コンパクションの前に使われていたトークン数です。

会話をフォークする#

フォーク（fork）は、新規で始まらず、ここまでの会話全体を引き継ぐサブエージェントです。サブエージェントが通常持つ入力の隔離はなくなり、フォークはメインセッションと同じシステムプロンプト・ツール・モデル・メッセージ履歴を見ます。状況を説明し直さずに副次的な作業を渡せます。フォーク自身のツール呼び出しはあなたの会話に出ず、最終結果だけが戻るので、メインの文脈ウィンドウはきれいなままです。ほかのサブエージェントでは背景の説明が多すぎて役に立たないとき、または同じ出発点から複数の方法を並行して試したいときに使います。

• Claude は、Agent ツールで fork というサブエージェントの種類を要求してフォークを始める。それを許すかはフォークモード（後述）で決まり、対話セッションでは既定で有効
• 自分で始めるには、/subtask にタスクを続ける。フォークモードの有無にかかわらず使える。v2.1.212 以降。v2.1.161〜v2.1.211 ではコマンドは /fork。Claude Code はタスクの最初の語からフォークに名前を付ける。エージェントビューを無効にすると /subtask は使えず、/fork がフォークしたサブエージェントを始める（そうでない場合の /fork は、セッション全体を新しいバックグラウンドセッションへコピーする）

/subtask draft unit tests for the parser changes so far

フォークは、プロンプトの下のパネルに出て、あなたが作業を続ける間バックグラウンドで動きます。終わると、結果がメインの会話にメッセージとして届きます。

動作中のフォークを見て操作する#

動作中のフォークは、プロンプト入力の下のパネルに、メインセッションの行とフォークごとの行で並びます。成功して終わったフォークの行は消えます。失敗した、または止めたフォークの行は、ほかのバックグラウンドのサブエージェントと同じく 30 秒残ります（v2.1.232 より前は、終わったフォークの行も 30 秒残っていた）。

フォークやサブエージェントの記録を開いている間は、フォローアップのメッセージとスキルはそのエージェントへ届き、組み込みコマンドはメインの会話へ届きます。ただし次の安全策があります。

• /compact・/clear・/rewind はメインの会話に作用するので、この画面から実行するときは Claude Code が確認を求める
• /model と /fast は、表示中のエージェントではなくメインの会話のモデルと fast mode を変えるので、この画面では実行されない。理由は通知で示される

表示中のエージェントが待っている作業の終了前に自分のメッセージを読ませるには、Ctrl+Enter か Ctrl+X Ctrl+S で送ります（キーボードショートカット）。エージェントが待っているシェルコマンドやサブエージェントのうちバックグラウンドへ移せるものは、バックグラウンドへ移って動き続けます。エージェントが応答を書いている最中や、バックグラウンドへ移せない作業を待っている間は、そのまま続けて、終わってからメッセージを読みます。v2.1.286 以降。

フォークと他のサブエージェントの違い#

フォークは、起動した瞬間のメインセッションが持つものをすべて引き継ぎます。ほかのサブエージェントは、定義からゼロで始まります。

• フォークのシステムプロンプトとツール定義は親と同一なので、最初のリクエストは親のプロンプトキャッシュを再利用する。同じ文脈が要る作業では、新しいサブエージェントを起動するより安くなる
• Claude が Agent ツールでフォークを起動するとき、isolation: "worktree" を渡すと、フォークのファイル編集があなたのチェックアウトでなく別の git worktree に書かれる。フォークはさらにフォークを起動できない

フォークモードをオン・オフする#

Claude Code は、対話セッションでは既定でフォークモードをオンにし、-p の非対話モードと Agent SDK では既定でオフにします。対話での既定は v2.1.232 以降が必要です（それ以前の版では、CLAUDE_CODE_FORK_SUBAGENT を 1 にするとオンになる）。フォークモードがオンのときは、Agent ツールの扱いが次のようになります。

• Claude は、fork の種類を要求してフォークを起動できる。種類を要求しないと、セッションにまだあれば、general-purpose のサブエージェントになる。Explore のように定義から作られるサブエージェントは通常どおり動く
• Claude Code は、Claude が起動するサブエージェントを、フォークも通常のものも、フォアグラウンドに残る場合を除き、バックグラウンドで動かす。Agent ツールの run_in_background パラメータも外すので、Claude はフォアグラウンドを求められない

環境変数 CLAUDE_CODE_FORK_SUBAGENT で既定を上書きします。

• 1：非対話モードと Agent SDK でもフォークモードをオンにする
• 0：あらゆる種類のセッションでフォークモードをオフにする

フォークモードをオンのまま、Claude がフォークを起動するのを止めるには、Agent(fork) ルールで fork の種類を拒否します。Claude Code は、Claude が起動するサブエージェントを、フォアグラウンドに残る場合を除き、引き続きバックグラウンドで動かします。

サブエージェントの例#

コードレビュー担当#

変更をせずにコードを見直す、読み取り専用のサブエージェントです。Edit と Write を外した限定的なツールアクセスと、見るべき点と出力の形を細かく指定したプロンプトの例です。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

デバッガー#

分析も修正もできるサブエージェントです。バグの修正にはコードの変更が要るので、レビュー担当と違い Edit を含みます。診断から検証までの流れをプロンプトで示します。

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

データサイエンティスト#

データ分析向けの専門サブエージェントです。通常のコーディング以外の専門的な作業用のサブエージェントの作り方と、より高性能な分析のための model: sonnet の明示を示す例です。

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

データベースクエリの検証担当#

Bash のアクセスは許しつつ、読み取り専用の SQL クエリだけを通すようコマンドを検証するサブエージェントです。tools フィールドより細かい制御が要るときの、PreToolUse フックによる条件つきの検証の例です。

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

検証スクリプトは、プロジェクトの好きな場所に作れます。パスは、フックの設定の command に一致させます。

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

• macOS・Linux では chmod +x ./scripts/validate-readonly-query.sh で実行権限を付けます。Windows では、スクリプトを PowerShell で書き、フックのエントリに shell: powershell を足します
• フックは、標準入力で JSON を受け取り、Bash コマンドは tool_input.command にあります。終了コード 2 は操作をブロックし、エラーメッセージを Claude に返します（終了コードと入力の形はフックのリファレンス）
• システムプロンプトが書き込みの依頼を断るよう指示しているので、フックは最後の砦です。サブエージェントが書き込もうとしても、Claude Code がコマンドをブロックし、サブエージェントに Blocked: Write operations not allowed. Use SELECT queries only. が見えます

関連#

• サブエージェントをチームやプロジェクトで共有するならプラグインを作って配る
• CI/CD や自動化には、ヘッドレス実行と Agent SDK
• サブエージェントに外部のツールやデータを渡すなら MCP サーバー