2026-10-22 公式ドキュメント更新：サブエージェント名の再起動復元とフックの上限制限が追加

Posted at 2026-10-29

2026-10-22 の更新は、サブエージェントの名前解決がコンパクション境界で変わるというルールの明文化と、v2.1.304 からスキルフックに登録数の上限が設けられたという2点を中心に、ループ停止操作の使い分け、パーミッションモードにおける critical-path removal の制限強化、サンドボックスのネストした名前空間に関する警告など、Claude Code を実運用する開発者が把握しておくべき細部を埋める記述が多数追加された日だった。

サブエージェント名の再起動後の復元ルールとMCPサーバー名の照合

Claude Code を再起動してセッションを再開した場合、サブエージェントを名前で呼び出せなくなるケースがある。今回の追加は、どの名前が生き残るかの境界を明示した。

Names Claude gave from the main conversation since its last compaction survive the restart.

（出典 [1]）

（訳：最後のコンパクション以降にメインの会話で Claude が付けた名前は、再起動後も生き残ります。）

それより前のコンパクションで付いた名前は失われる。その場合はエージェント ID を直接渡してメッセージを送ると、以降は名前でも呼び出せるようになる。ID は ~/.claude/projects/{project}/{sessionId}/subagents/ 以下の agent-{agentId}.meta.json ファイルで確認できる。v2.1.299 以前ではコンパクション境界にかかわらず名前がすべて失われていた点も併せて記された。

MCP サーバー名にダブルアンダースコア（）が含まれる場合のツール照合の問題も追加された。reports__v2 のようなサーバーの場合、サブエージェントの tools エントリには mcp__reports__v2* と末尾の * まで含めて書く必要がある。末尾を省くと報告されたサーバーのツールがひとつも一致しない。また disallowedTools に mcp__reports または mcp__reports* を書くと、reports というサーバーを除外しようとした意図であっても reports__v2 のツールもすべて失われる。特定のサーバーだけを除外したい場合は mcp__reports__run_query のように個別に列挙する必要がある。

ループの停止方法とデタッチ操作の仕様整理

/loop によるループには大きく2種類あり、停止の操作が異なることが明確に書き分けられた。

セルフペース（自動間隔）のループは、次の実行を待っている間に Esc を押すと停止できる。一方、固定間隔のループは動作が異なる。

Fixed-interval loop : to stop a loop such as /loop 5m , ask Claude to cancel it, for example cancel the deploy check loop .

（出典 [3]）

（訳：/loop 5m のような固定間隔のループを止めるには、「deploy check loop をキャンセルして」のように Claude にキャンセルを依頼します。）

固定間隔のループは Esc でも Ctrl+C でも止まらない。ループを止めないままデタッチする操作も追加された。バックグラウンドセッションへのアタッチ中に Ctrl+C を2回、空のプロンプトで押すとセルフペースのループを動かしたままデタッチできる。この機能は v2.1.295 以降で使える。デタッチより先にループを止めたい場合は Esc を押してから抜けると停止できる。

バックグラウンドセッションのプロセスが停止した状態（クラッシュ後など）で次の起動タイミングが来ると、ループは止まる。再開後にセッションへ返信してループを続けるよう Claude に依頼するとループが再開する。この場合、停止中に来るはずだった実行はスキップされ、再開後の最初の実行はジッターが適用される。また、claude --resume や claude --continue で再開しても、停止前に動いていたバックグラウンドの Bash コマンドやモニターは再起動されない。必要であれば改めて起動を依頼する必要がある。

スキルフックの登録上限（v2.1.304 以降）

v2.1.304 以降、スキルフックの登録数にソースごとの上限が設けられた。

each source of skills has its own limit per session.

（出典 [11]）

（訳：スキルの各ソースはセッションごとに独自の上限を持ちます。）

プロジェクトのスキル、個人スキルフォルダ、各プラグインはそれぞれ別のソースとして扱われる。1ソースあたりの上限は 1,024 フック（2026-10-22 時点）で、マッチャー文字数の合計は 16,384 文字が上限だ。同一のマッチャーに複数フックが付いている場合は、フックの数だけカウントされる。

上限を超えたスキルはそのソースのフックを一切登録せずに動作する。デバッグ方法は、claude --debug で新しいセッションを始め、同じスキルを同じ順で呼び出した後、ログで "registers none of its hooks" という文字列を探すと、どのスキルが上限を超えたか分かる。対処は、フック数やマッチャーの文字数を減らすか、スキルをプラグインに移動することだ。

なお Enterprise の管理設定で strictPluginOnlyCustomization が有効な場合、フロントマターのフックが動くのはプラグインスキル、バンドルスキル、管理設定ディレクトリのスキルに限られる。自分の設定ファイルのフックも動かない点に注意が必要だ。

パーミッションモードと critical-path removal の制限の明文化

パーミッション制御まわりで、どのルールや設定でも例外なく通過できない操作について複数の記述が追加された。

A hook that returns allow doesn't skip the deny and ask rules below, which are evaluated regardless of the hook result.

（出典 [15]）

（訳：allow を返すフックは、その下にある deny ルールや ask ルールをスキップしません。これらはフックの結果にかかわらず評価されます。）

rm -rf / や rm -rf ~ といった critical-path removal は、allow ルールや PreToolUse フックが allow を返しても承認されない。bypassPermissions モードでも同様の制限が適用される。加えて、AskUserQuestion ツール、requiresUserInteraction が付いた MCP ツール、組織が ask に設定したコネクターツールも allow ルールでは自動承認されない。

claude agents で bypassPermissions の警告が表示され続ける場合は、skipDangerousModePermissionPrompt の設定場所の確認が必要だ。interactive セッションは .claude/settings.local.json や --settings ファイルにあるそのキーを設定済みとして扱うが、claude agents はそうしない。claude agents が警告を読む ~/.claude/settings.json で受け入れる操作が必要になる。

その他の更新

ワークツリーの削除確認（worktrees）: ワークツリーが自身のブランチ以外にある状態で、そのブランチに開始コミット以降のコミットが存在する場合、削除時に保持か削除かを確認するプロンプトが表示される。どちらを選んでも、もとのブランチとそのコミットは残る。
managed CLAUDE.md の除外制限（memory）: claudeMdExcludes で managed CLAUDE.md を除外することはできない。ガイダンスにはファイルを使い、ルールの強制には permissions.deny などの managed settings を使うよう記載された。
Enterprise スケジュールタスクの権限（routines）: カスタムロールを使う Enterprise 組織では、スケジュールタスクを利用するためにそのロールに scheduled tasks 権限が Remote sessions セクションに含まれている必要がある。権限がなくても web の claude.ai/code/routines から作成・管理はできる。
ツール概要の整理（tool-use overview）: クライアントツールとサーバーツールの区別、およびコードの実行場所の説明が整理された。tool runner を使うと round trip の実装が不要になる旨も追記された。
スキルのパス制限（slash-commands, skills）: skill の paths 設定はカレントワーキングディレクトリからの相対パスを基準にする。/add-dir で追加したサブディレクトリや隣接する git worktree でもそのスキルは働かない。対象ディレクトリで Claude Code を起動するか /cd で移動する必要がある。また、スキルフォルダに .claude-plugin/plugin.json を追加すると、そのフォルダをプラグインとして読み込める。
settings の説明（settings）: ~/.claude/settings.json はアカウント情報、MCP サーバー設定、プロジェクトごとの信頼決定、/config が書くグローバルキーを保持する旨が明記された。
MCP バックグラウンドコマンドの出力（mcp）: backgroundOutputPath フィールドを使うとバックグラウンドで起動したコマンドの出力ファイルを読み取れる（v2.1.295 以降）。終端の検知には固定文字列の echo を末尾に付けるのが推奨されている。
サンドボックスの allowNestedUserNamespaces（sandboxing）: v2.1.305 以降で設定可能になったこの設定を true にすると、サンドボックス内のコマンドがサンドボックス外でコードを実行できる状態になり、protected paths や credentials.files の制限も信頼できなくなる。組織のセキュリティチームに確認してから使うよう推奨されている。
プロンプトエンジニアリング概要（prompt-engineering overview）: すべての評価基準や failing eval がプロンプトエンジニアリングで解決できるとは限らない点と、別モデルの選択によるレイテンシ・コスト改善の可能性が言及された。

まとめ

この日の更新は、Claude Code を長期的・組織的に運用しているチームに直接影響する変更が揃っている。サブエージェントの名前解決がコンパクション境界で変わるという整理と、v2.1.304 からのフック上限は、既存のマルチエージェント構成や大量フック構成を見直すきっかけになる。ループの停止操作の使い分けとデタッチ操作の挙動は、バックグラウンドセッションを常時使っているチームに実運用上の違いをもたらす。パーミッション制御まわりの追記は挙動の明文化であり新機能ではないが、allow ルールが通過できないアクションの一覧が整理されたことで、SDK や Agent 環境でのパーミッション設計の根拠として参照しやすくなった。

出典

本稿の引用はすべて一次資料と逐語照合（verify_article 通過）のうえ掲載しています（2026-10-30 検証）。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up