Claude Code modが動かないときの切り分け — 症状別の原因とデバッグログ

Claude Code modが動かないときは、まず「modそのものが読み込まれたか」を確かめます。modのモジュールやhookが失敗すると、Claude Codeはそれを飛ばしてセッションを続けるため、壊れたmodは「何もしないmod」に見えるからです。手がかりは、modの名前を含む1行のメッセージです。その行を読む場所と、メッセージごとの原因を症状別にまとめます。

症状とメッセージの逆引き

見えている症状から、探すメッセージと出る場所を引きます。右端の列は、原因を詳しく書いた節です。

最初の4手 — 読み込み状態を確かめる

原因を探す前に、次の4つを順に試すと、問題が「読み込み前」か「読み込み後」かが分かります。

claude plugin validate ./first-mod
cd ~ && claude plugin test
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

claude plugin testの返すメッセージは、読み込める環境かどうかを次のように分けます。

組織がallowManagedModsOnlyを設定している場合、このコマンドは報告しません。その場合は、インストールしたmodが拒否されたとき別のメッセージで理由が出ます。

手元のclaudeで確かめた出力

空のCLAUDE_CONFIG_DIRでclaude --versionとclaude plugin validate --helpを実行すると、v2.1.296では次のとおりでした。ログインやモデル呼び出しは伴いません。

$ claude --version
2.1.296 (Claude Code)
 
$ claude plugin validate --help
Usage: claude plugin validate [options] <path>
 
Validate a plugin or marketplace manifest, or the skills, agents, and commands
in a directory
 
Options:
  -h, --help  Display help for command
  --json      Output the validation report as JSON (same exit codes)
  --strict    Treat warnings as errors (exit 1). Use in CI to fail on
              unrecognized fields, missing metadata, and other issues that the
              runtime tolerates.

--helpの説明文が挙げる検査対象は、manifest、skills、agents、commandsです。troubleshootページが書く「イベント名の綴り間違いや読めないモジュールを拾う」は、この説明文からは読み取れません。CIに組み込むなら--strictを付けると、実行時には許容される未認識フィールドも終了コード1で落とせます。modのhookまで検査対象に含まれるかは、手元のmodに綴り間違いを仕込んで試すのが確実です。

メッセージはどこに出るのか

modを名指しする1行は、セッションの種類によって出る場所が違います。ここを取り違えると「何も出ない」と誤解します。

マーケットプレイス経由のmodが動かないのにtranscriptが静かなのは、不具合ではなく仕様どおりです。最初から--debugを付けて起動し直すのが近道です。

症状1: modが読み込まれない

コマンドも描画も挙動の変化もなく、mods activeの行にも名前がない状態です。debugログには、hooks module、modの名前、not loaded:で始まる行が出ます。たとえば--plugin-dirで読んだmodならhooks module first-mod@inline not loaded: disableAllHooks in managed settingsの形です。コロンの後ろが理由です。

この表に当たらない場合は、次の原因を上から確かめます。

• バージョンが古い: ターミナルではv2.1.287以降、Desktopアプリではv2.1.286以降が必要です。claude --versionで確かめます。
• validateは通るのにhooksの行が出ない: hooks/hooks.jsonにmodulesキーがないか、綴りが違います。"modules": ["./register.js"]を足します。
• hooks module did not load:: モジュールの読み込みに失敗しています。トップレベルのコードが例外を投げた場合などで、理由にはファイルと行が出ます。示されたエラーを直します。
• options do not fit plugin.json userConfig: オプションがuserConfigの検証に失敗しています。maxを超える数値や、必須項目の未入力が典型です。行の末尾にsettings.jsonのpluginConfigsのエントリ名が出るので、そこの値を直します。
• 初めて開いたディレクトリで何も読まれない: trustプロンプトに答えていません。そのディレクトリでclaudeを対話起動して受け入れます。
• インストール済みプラグインがすべて読まれない: --safe-modeで起動していないか確かめます。--safe-modeそのものの使い方はClaude Codeのsafe modeにまとめています。

組織管理の端末やTeam・Enterpriseプランでは、組み込みの保護機構がmodやその応答を拒否することもあります。メッセージにmods are limited to your organization's by policy (allowManagedModsOnly)が含まれていれば、管理者が組織のmodだけを許可しています。debugログのほか、ホットリロード中のセッションではtranscriptにも出ます。

症状2: hookがスキップされる、modが外される

modは読み込まれたのに、特定のhookが飛ばされる、あるいはmodごと外されるケースです。メッセージで原因が分かれます。

no command.run hook answered itには、もうひとつの原因があります。hookがスキップされている場合で、$.ui.openにfocus: falseを渡したときもここに入ります。hookが確かに書いてあるなら、command.runに言及するhook skippedの行を探してください。理由はそこに出ます。テストでコマンドを実行しても同じ理由で失敗するので、再現にも使えます。

インストール済みmodは1つのワーカースレッドを共有しています。ワーカーが応答しなくなったり落ちたりして、原因がこのmodと突き止められると外されます。awaitのないループでスレッドを塞ぐhookが、原因のひとつです。

session.startの再実行は、ワーカーの入れ替えなどで起きます。$.prompt.submit・$.command.run・$.agent.spawnの呼び出しは最初の結果を返すだけで再実行されないため、直すことはありません。v2.1.292より前は、この呼び出しが2回実行され、プロンプトの送信やサブエージェントの起動が重複していました。

症状3: ツール呼び出しが拒否される

modもhookも動いているのに、modが触れたツール呼び出しが拒否されるケースです。拒否の理由として、次の2系統があります。

auto modeの「a hook changed this call's input」

auto modeでは、サーバー側の分類器が審査したあとにhookが呼び出しの入力を書き換えると、審査が実際に実行される内容をカバーしなくなるため拒否されます。書き換えたのはmodのtool.call・turn.stephookでも、settingsのPreToolUsehookでもありえて、メッセージはどれかを示しません。Claudeには「記録されたとおりにもう一度呼び出す」よう伝わります。それでも拒否されるなら、hookが毎回入力を書き換えています。modかhookを止めるか、auto modeを離れて自分で承認します。審査の仕組みはauto modeのサーバー側審査で扱っています。

設定のdenyルールに関するメッセージ

tried to lift a deny rule in your settingsは、modのtool.checkhookが、denyルールで拒否される呼び出しを承認しようとした場合に出ます。呼び出しは拒否されたままです。transcriptとdebugログにmodごと1セッション1回出ますが、claude -pではdebugログのみです。tool.checkで読めるフィールドはmodのtool.check解説にあります。

もう一つのthe deny rules in your settings could not be checked for this call, so it is refusedは、modが承認した呼び出しの検査自体が失敗したため拒否した、というメッセージです。こちらは拒否された呼び出しについてClaudeが読む理由に入ります。

どちらも、modがdenyを越えられない設計の結果です。対処はmodのhookを直すか、必要ならdenyルールの側を管理者と見直すことになります。

症状4: 描画が出ない、反応しない

ペイン、バンド、トースト、キー操作のいずれかが期待どおりに動かないケースです。

• ペインやバンドが空、またはClaude Code標準の表示のまま: hookが返したツリーの検証が通っていません。--plugin-dirならtranscriptにui.render (Pane) refused:と理由が出ます。debugログにはa hook returned a tree that does not validateが出ます。要素が受け付けないpropや、アプリに存在しない要素が典型です。
• threw while drawn:: 返されたツリー、またはnextに渡したpropsを描く途中でエラーになっています。末尾のthe engine drew its ownは、その場所が標準表示にフォールバックしたという意味です。v2.1.289より前は、transcriptの行でこのエラーが起きるとセッションが終了していました。
• the module failed without a message: Clientがthrow new Error()のようにメッセージのないエラーで失敗しています。Clientのコードでthrowを探してメッセージを付けます。Clientの失敗をhookで受けて描き直す方法はui.faultの解説にあります。
• $.ui.openを呼んだのにペインが出ない: ユーザー操作に由来しない呼び出しで、しかも端末がそのペインの必要幅より狭いと表示されません。コマンドやボタンから開くか、戻り値のisPlacedを確かめます。
• ホットキーが効かない: ペインにキーボードフォーカスがありません。Ctrl+Xに続けてTabを押すか、ペインをクリックします。コマンドから開くときはfocus: trueを付けます。
• ターミナルでは動くのにDesktopアプリで描かれない: そのレンダリング箇所や要素がDesktopでは使えません。リファレンスのrender sitesとelementsの表で対応面を確かめます。

トーストが出ないとき

対話ターミナルで$.ui.toastを呼んでも見えないときは、まずdebugログで呼び出しの行を探します。$.ui.toast (first-mod): build finishedのように、modの名前とトーストの文言が出ているはずです。行がない場合は、$.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000のような拒否理由の行を探します。行があるのに見えないときの原因は次のとおりです。

v2.1.290より前は、前回のトーストから2秒以内に出したトーストが捨てられていました。その場合のログはwithin 2000ms of the last; droppedでした。

症状5: 編集や値が消える

modは動いているのに、直したはずの変更や、保存したはずの値が見当たらないケースです。原因は3つに絞れます。

1. 編集が反映されない: インストール済みのプラグインを編集しています。Claude Codeが動かすのは、インストール版のキャッシュです。claude --plugin-dir ./first-modで作業コピーを指して開発すると、保存のたびに再読み込みされます。
2. モジュールの再読み込みで値が戻る: モジュールレベルの変数は再読み込みのたびに初期化されます。値は$.stateか$.storeに置きます。
3. /clear・/resume・/branchのあとで値が戻る: どのコマンドも$.stateを既定値に戻し、session.startは再発火しません。保存した値の読み込みはclassic.SessionStarthookで行います。

--plugin-dirで編集しているときは、再読み込みのたびにmodの名前とhookの一覧がtranscriptに出ます。保存で壊れた場合はreload failed, the previous version stays loaded:に理由が続き、最後に動いた版が、次に/reload-pluginsなどでプラグインが再読み込みされるまで動き続けます。保存したのに変わらないときは、この行を探します。

debugログの読み方

debugログには、読み込んだ・拒否したモジュール、失敗したhook、拒否した結果の行が1つずつ残ります。transcriptが静かなときの最後の頼りです。

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
# 別の端末で
tail -f ./mod-debug.log | grep first-mod

読み込めたmodには、名前と処理するイベントを並べた行があります。--plugin-dirで読んだmodは名前の後ろに@inlineが付きます。

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

events:の並びに、期待するhookのイベント名があるかを確かめます。自分の調査用の行を足すには、$.ui.log('message', { to: 'debug' })と第2引数を付けます。第2引数がないと、transcriptに薄い色の行が追加されます。

切り分けを早くする順序

メッセージが見つからないときは、読み込みの前後で2つに割ると速く進みます。mods activeの行に名前があるかが分かれ目です。

• 名前がない: 症状1の表。debugログでnot loaded:を探す
• 名前がある: hook skippedの行、refused:の行、threw while drawn:の行のどれかをdebugログから探す

modを作る側なら、セッションを開く前にclaude plugin validateとclaude plugin testを回せば、イベントの綴りやhookの例外はここで落とせます。modの作り方そのものはmodを80行で作る手順にあります。

まとめ

modが何もしないように見えるのは、失敗がセッションを止めずに1行のメッセージだけで流れるためです。読む場所はセッションの種類で変わり、マーケットプレイスで入れたmodは--debugで起動しないとログすら残りません。まずmods activeの行で読み込みの前後を分け、読み込み前ならrefusalの表、読み込み後ならhook skippedやrefused:の行を、modの名前でgrepして追うのが最短です。