「調査だけを任せたいのに、担当がファイルを書き換えたり、勝手にコマンドを実行したりしないか心配です」
「担当の定義ファイルを置いたのに、担当の一覧に出てきません。エラーも出ないので、どこが悪いのか分かりません」
第3回(担当を定義する)では、担当(サブエージェント)の定義のファイルの形、フィールドの一覧、description の書き方を見ました。定義が書けても、何ができる担当にするかと、何をどんな形で返させるかを決めなければ、安全にも使いやすくもなりません。さらに、書いたはずの定義が、黙って読み込まれないことがあります。
第4回では、tools で担当のできることを絞る方法、返す形と「遭遇した障害」の欄、定義の反映のタイミングと読み込まれないときの原因を扱います。冒頭の1つ目の相談は「tools で『できること』を絞る」の節、2つ目の相談は「反映のタイミングと、読み込まれないとき」の節が答えです。数値・仕様は2026年10月時点です。
tools で「できること」を絞る
担当に使わせる道具は、定義の tools に書いて許可リストとして絞ります。役割ごとに、必要な道具だけを渡します。
| 役割 | tools | できること |
|---|---|---|
調査(infra-researcher) | Read, Grep, Glob | 読むだけ。変更できない |
レビュー(playbook-reviewer) | Read, Grep, Glob, Bash | +git diff などの実行。Edit・Write なし |
作成(playbook-writer) | Read, Grep, Glob, Edit, Write, Bash | +ファイルの編集・作成 |
| 省略 | 書かない | 本体の道具を全部引き継ぐ。広すぎる |
| Bash の一部だけ止める | 権限ルール permissions.deny に Bash(git push *) | 担当にも本体にも効く(公式の sub-agents。ルールの書き方は連載「Claude Code実践入門」第6回) |
表の3つの担当(infra-researcher・playbook-writer・playbook-reviewer)は、この連載で使う筆者の例です(役割とモデルの対応は第6回の「役割とモデルの対応(筆者の例)」、3つのひな形は第9回の「3役のひな形(筆者の例)」で扱います)。

補足:disallowedTools は外す一覧で、Bash(git push *) と書いても Bash 全体が外れます。tools に許可リストを書いた担当は、Agent を入れなければほかの担当を呼びません。tools を省いた担当は、既定では本体の下に3層まで担当を呼べます。出典:https://code.claude.com/docs/ja/sub-agents 、https://code.claude.com/docs/ja/tools-reference (tools は許可リスト)(deny のルールは本体にも担当にも効く、は sub-agents のページの記述)
表の読み方を、公式の記述に沿って補います。
- 省略すると引き継ぐ:担当は、本体で使える組み込みの道具と MCP の道具を引き継ぎ、
tools(許可リスト)とdisallowedTools(外す一覧)の2つの絞り込みで狭められる。toolsを書かない担当は、道具を全部引き継ぐ - 両方書いたときの順番:
disallowedToolsを先に適用し、残った道具に対してtoolsを解く。両方に書いた道具は外れる - Bash の一部だけ止める:
disallowedToolsにBash(git push *)のような指定を書くと、一致するコマンドだけでなく Bash の道具ごと外れる。Bash を残して特定のコマンドだけ止めたいときは、settings のpermissions.denyにBash(git push *)を書く。この deny ルールは本体にも担当にも効く。ルールの書き方と限界は、連載「Claude Code実践入門」第6回の「allow・ask・denyルールの書き方」「前方一致の落とし穴と、denyの限界」で扱っています - 担当がほかの担当を呼べるか:既定では、担当が自分でさらに担当を呼べる(本体の下に3層まで)。
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで段数を変えられ、1にすると入れ子を使えない(v2.1.217 以降)。入れ子が使える設定で、レビュー担当のように読むだけにしたい担当に呼ばせたくないときは、公式はtoolsの一覧にAgentを入れない(またはdisallowedToolsに入れる)と書いています
筆者が非対話の claude -p(Claude Code 2.1.302)で試したところ、tools: Read, Grep, Glob, Bash のレビュー担当は、Edit を使わずに git diff・ansible-lint・構文チェックを実行して、結果を返してきました(演習は第13回の手順5)。
返す形と、障害の報告
担当は、作業の経緯を本体に見せず、最後に返す1通の報告だけを本体に渡します。その報告の形を、定義の本文に書いておきます。
- 返す形を本文に書く:セクションを埋め終えたら止まる、という自然な止まりどころができる。書かないと、必要以上に長く走り続けやすい(Academy レッスン3)
- 「遭遇した障害」の欄:回避策、特別なフラグが要ったコマンド、環境の癖を書かせる。本体が同じ回り道を繰り返さずに済む
- 筆者の例:Ansible のコマンドは
2>&1 | catを付けないと止まる。成否は PLAY RECAP で見る、と報告させる - 足さない一文:「あなたは○○の専門家です」(第2回の「使う・使わないの判断ルール」)
「筆者の例」の 2>&1 | cat は、Claude Code から Ansible を実行すると「Ansible requires blocking IO」で止まることがある、という筆者の環境の癖です(連載「Claude Code実践入門」第4回の「チームで共有するCLAUDE.mdのひな形(筆者の例)」の「環境の癖」で説明しています)。終了コードは cat の0になるので、成否は出力の PLAY RECAP で判断させます。
返す形は、定義の本文に次のように書きます(レビュー担当の例です)。
次の形で返してください。
## 概要
## 重大(直ちに直す)
## 主要
## 軽微
## 推奨
## 判定(そのまま進めてよいか)
## 遭遇した障害(回避策・特別なフラグのいるコマンド・環境の癖)

補足:レビュー担当の返す形の例です。出典は Academy のレッスン3 https://academy.claude.com/ja/courses/introduction-to-subagents/designing-effective-subagents と、公式の Code reviewer の例です。
公式の Code reviewer の例は、読むだけのレビュー担当(Edit・Write を持たない)の本文で、「Critical issues (must fix)」「Warnings (should fix)」「Suggestions (consider improving)」の優先度順に返させています。「遭遇した障害」の欄は、Academy のレッスン3が勧めるものです(筆者が確認した範囲では、公式の例の担当に障害を報告させる節は見つかりませんでした)。
もう1つの止めどころとして、定義の maxTurns があります。担当が上限の回数に達すると、Claude Code は出力を「部分的な結果」と印を付けて返し、Claude は続きを再開できます(この印は v2.1.246 以降)。
筆者が試したとき、レビュー担当は「担当が確認したこと(lint 0・構文成功)」と「まだ確認していないこと(stg への --check --diff、冪等性)」を分けて返してきました。返す形に「判定」と「障害」の欄を持たせると、確かめていないことが報告に残ります。
反映のタイミングと、読み込まれないとき
定義のファイルを置いたら、すぐ使えるのか、それとも再起動が要るのか。そして、定義がなぜか読み込まれないとき、どこを見るのか。
- 反映:
.claude/agents/への追加・編集(Claude に書かせた場合も)は数秒で反映され、再起動は要らない(公式) - 再起動が要る場合:セッション開始時に無かった
agentsフォルダーの最初のファイル、--add-dirで足したフォルダー、--disable-slash-commandsのセッション。Code タブでの動きは筆者は確かめていない - 黙って読み飛ばされる:
nameが無い、先頭行が---でない、nameだけでdescriptionが無い、YAML の誤り - 筆者の CLI(2.1.289)で確かめた:
descriptionの無い定義は担当の一覧に出ず、エラーの表示も無かった。Code タブの表示は筆者は確かめていない - 点検:
claude plugin validate .claude/agents(v2.1.233 以降)。Code タブで Claude に実行させられるかは、筆者は確かめていない - 使わせない担当:
permissions.denyにAgent(名前)(組み込みにも効く)
補足:読み飛ばしの理由は claude --debug のログにだけ出ます。出典は https://code.claude.com/docs/ja/sub-agents です。

読み飛ばしと再起動について、公式の記述を補います。
- 再起動が要る理由:Claude Code が監視するのは、セッションの開始時に存在した
~/.claude/agents/と.claude/agents/などのフォルダーだけ。新しく作ったフォルダーの最初のファイルは、再起動して読み込ませる nameが無い定義:読み飛ばされるというより、担当ではなく「担当のそばに置いた文書」として扱われるnameだけでdescriptionが無い定義:読み飛ばされ、理由はデバッグのログに書かれる。筆者の記録(2.1.289)の「一覧に出ず、エラーも出ない」と合う- フォルダーの中の定義を点検する:
claude plugin validateに.claude/agentsや~/.claude/agentsのフォルダーを渡すと、frontmatter が読めないファイルを見つけられる - デバッグのログ:Claude Code を
--debug付きで起動すると見られる
定義を Claude に書かせたとき、.claude/ の下への書き込みは保護されたパスなので確認の画面が出ます。筆者が claude -p(2.1.302)で準備を試したときも、3つの定義の書き込みは承認待ちになりました。確認の内容を見て許可すれば、数秒で担当として使えるようになります。
考えてみよう
- 調査だけを任せたい担当の
toolsは、どう書きますか。toolsを書かなかったら、何が起きますか - 担当を
git pushだけ止めたいとき、disallowedToolsにBash(git push *)と書くのと、permissions.denyに書くのとでは、何が違いますか - 置いたはずの定義が担当の一覧に出ないとき、確かめるものを3つ挙げてください
ヒント:1は「tools で『できること』を絞る」の表、2は同じ節の補足、3は「反映のタイミングと、読み込まれないとき」の節を見直してください。
まとめ
toolsは許可リスト。調査はRead, Grep, Glob(読むだけ)、レビューは+Bash、作成は+Edit, Write。書かないと本体の道具を全部引き継ぐ- Bash の一部だけ止めるには、
disallowedToolsではなくpermissions.denyのBash(git push *)。disallowedToolsに書くと Bash 全体が外れる。deny は担当にも本体にも効く toolsに許可リストを書き、Agentを入れなければ、担当はほかの担当を呼ばない。toolsを省くと、既定で本体の下に3層まで呼べる- 返す形を本文に書くと、止まりどころができる。「遭遇した障害」の欄で、回避策・特別なフラグ・環境の癖を本体に返させる
.claude/agents/の追加・編集は数秒で反映される。再起動が要るのは、新しいagentsフォルダーの最初のファイル、--add-dir、--disable-slash-commandsnameが無い、先頭行が---でない、descriptionが無い、YAML の誤りは黙って読み飛ばされる。理由はclaude --debugに出る。claude plugin validate .claude/agents(v2.1.233 以降)で点検する
次回は、担当のモデルの決まり方(model に書ける値、決まる順番、別名で書く理由、組織の許可リスト)を扱います。
連載「Claude Codeサブエージェント入門」全13回
全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。
- サブエージェントとは
- 組み込みの担当と使い分け
- 担当を定義する
- toolsと返す形(この記事)
- 担当のモデルの決まり方
- 役割とモデル・effort
- スキルから担当を呼ぶ
- 順に使う・前と裏
- ログの要約とレビューの担当
- 費用を測って小さく使う
- 演習(前編):準備
- 演習(中編):読み込む・呼ぶ・モデルを見る
- 演習(後編):レビュー・スキル・費用

コメント