Claude Code v2.1.323のCode Modeとプラグイン互換性：無人実行へ取り込む前に確認すること

Claude Codeの新機能は、追加されたことよりも「いつもの運用に混ぜて大丈夫か」を見極めるほうが難しいものです。2026年11月のv2.1.323では、実験的なCode Mode、プラグインの対応バージョン指定、長時間hookの進捗表示などがCHANGELOGに追加されました。

Code Modeは便利そうだからこそ実験扱いにする

Code Modeは、ClaudeがJavaScriptを書いてツールを呼び出す実験的なオプトイン機能です。複数のツール呼び出しをまとめたり、結果を加工してから次の処理へ渡したりできる可能性があります。一方で、通常のツール呼び出しと実行境界が変わるため、既存の許可設定やログの見え方まで同じだと決めつけるのは危険です。

最初から常用設定にするのではなく、読み取り専用の小さな作業で試します。対象ディレクトリを限定し、外部送信やファイル削除を含む作業には使わない。実行前後に「どのツールを何回呼んだか」「生成されたJavaScriptが何をしたか」を確認できる状態を作ってから、便利さを評価する順番です。

プラグインはClaude Codeの対応範囲を確認してから更新する

v2.1.323では、プラグインのplugin.jsonにengines["claude-code"]を指定できるようになりました。プラグインが想定するClaude Codeのバージョン範囲に合わない場合、インストール・更新・読み込みの対象から外れます。

これは「急にプラグインが壊れた」というより、互換性のない組み合わせを早い段階で止めるための仕組みです。更新後にプラグインが見えなくなった場合は、まずプラグインの対応範囲と自分のClaude Codeのバージョンを確認します。対応範囲を無視して読み込ませる回避策を探すより、両方を対応する版へそろえるほうが安全です。

{
  "engines": {
    "claude-code": ">=2.1.323"
  }
}

上の例は形式を示すだけで、実際のプラグインがこの範囲を要求するという意味ではありません。導入時は必ず対象プラグイン自身のplugin.jsonを確認してください。

長いhookを「固まった」と誤認しないためのheartbeat

長時間かかるhookに対して、v2.1.323ではclaude -pやSDKセッションで30秒ごとの進捗heartbeatが追加されました。処理が終わっていなくてもホスト側が「まだ動いている」と判断しやすくなります。

ただしheartbeatは処理を速くする機能ではありません。無人実行では、heartbeatを完了通知と取り違えず、終了コードや最終結果を別に確認します。一定時間heartbeatが止まった場合も、即座に二重起動せず、ログとプロセスの状態を確認してから再試行します。

安全な試し方を小さく固定する

1. 変更前にClaude Codeとプラグインのバージョンを記録する。
2. Code Modeは読み取り専用・小容量の作業でだけ試す。
3. プラグインのengines条件を確認し、対応外の版を無理に読み込ませない。
4. hookはheartbeatと完了結果を分けて監視する。
5. 問題が出たらCode Modeを無効化し、通常のツール呼び出しへ戻して差分を切り分ける。

Claude Codeの新機能は、便利さだけを見て全体へ広げるより、境界を限定して観測したほうが失敗時の復旧が簡単です。特に無人実行やプラグイン共有環境では、「使えるか」より「戻せるか」を先に決めておくのが現実的です。

まとめ

v2.1.323で注目したいのは、Code Modeそのものだけではありません。実験機能を小さく試すこと、プラグインと本体の対応範囲を明示すること、長い処理の生存確認と完了確認を分けること。この3点を押さえると、新しい自動化機能を無人処理へ取り込むときの判断がしやすくなります。

関連して、Claude CodeのプラグインとSkills/MCPの違い、MCPタスクをバックグラウンド化する考え方も整理しています。