mod のトラブルシューティング

Claude Code mod が何もしない理由を調べます。症状またはメッセージを原因と照合し、拒否メッセージを確認し、デバッグログを読みます。

mod のモジュールまたはそのいずれかのフックが失敗すると、Claude Code はそれをスキップしてセッションが続行されるため、壊れた mod は何もしない mod のように見えることがあります。Claude Code が mod から読み込んだ内容と、問題を報告する場所を確認することから始めてください。その後、症状またはメッセージを見つけてください。

mod が何もしない理由を調べる

mod が何もしない場合は、Claude Code が mod のファイルから読み込む内容と、何かをスキップするときに書く行を確認します。前者については、シェルで claude plugin validate を mod のディレクトリで実行します。例えば claude plugin validate ./first-mod のようにします。セッションを開始せずに、スペルが間違ったイベント、不正なマニフェスト、Claude Code が読み込めないモジュールをキャッチします。

モジュールが読み込まれない場合、hooks がスキップされる場合、または別の mod があなたの mod を拒否する場合、Claude Code は mod の名前を付けた 1 行を書きます。その行を読む場所はセッションによって異なります。

• プラグインディレクトリをホットリロードするセッション: トランスクリプト内の薄い行。これは --plugin-dir で開始した対話型セッション、または Claude が書いた mod の ホットリロードを有効にした セッションです。
• マーケットプレイスからインストールした mod を実行するセッションなど、その他の対話型セッション: デバッグログ のみ。取得するには、セッションを claude --debug で開始します。
• --plugin-dir を使用した claude -p 実行: stderr、デフォルトのテキスト出力形式で。別の mod による拒否はデバッグログのみに移動します。

mod が読み込めるかどうかを確認する

mod が読み込めるかどうかを確認するには、mod をインストールせずに、シェルから claude plugin test を実行します。mod を保持していないディレクトリから実行します。セッションは不要です。出力されるメッセージは状態を示します。

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

mod が読み込まれない

mod が追加するものは何も表示されません。コマンド、描画、動作の変更はありません。

バージョンが古すぎる

使用するバージョンとバージョンの確認方法を参照してください。

mods active 行が mod の名前を示していない

mod が追加するものは何も表示されず、/plugin の mods active 行 にその名前がありません。hooks モジュールが読み込まれませんでした。Claude Code がそれを拒否したとき、デバッグログには hooks module、mod の名前、not loaded: で始まる行があります。例えば --plugin-dir で読み込まれた mod の場合 hooks module first-mod@inline not loaded: disableAllHooks in managed settings のようになります。

コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。ログにそのような行がない場合は、このグループの他のエントリを確認してください。

一部の設定は mod を停止しますが、そのプラグインの残りの部分は動作したままにします。mod をオンまたはオフにする でそれらの設定を挙げています。

claude -p 実行が hooks module not loaded を出力する

行は mod の名前で始まり、stderr に移動します。hooks モジュールが拒否されました。非対話型実行にはトランスクリプトがないため、メッセージは stderr に移動します。

コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。

拒否メッセージ

これらはそれぞれ、デバッグログの hooks module、mod の名前、not loaded: に続きます。

組み込みガードからのメッセージ

管理設定を持つマシン上、または認証情報が Team または Enterprise の /login であるセッションでは、組み込みガード は mod またはそのいずれかの回答を拒否できます。各メッセージは、組織の管理者が設定するオプションの名前を示します。

validate が成功し、hooks 行がリストされていない

hooks/hooks.json に modules キーがないか、キーのスペルが間違っています。

"modules": ["./register.js"] を追加します。

hooks module did not load

行は mod の名前で始まり、hooks module did not load: と理由が続きます。問題がコード内にある場合、ファイルと行を示します。Claude Code はモジュールを読み込めませんでした。例えば、トップレベルコードが例外をスローしたためです。

理由が示すエラーを修正します。

理由が ; the version loaded before is unloaded で終わる場合、現在実行中の mod のバージョンはありません。エラーを修正したら、セッションで /reload-plugins を実行して mod を再度読み込みます。mod を自分で書いたのではなくインストールした場合は、作成者にエラーの修正を依頼してください。

options do not fit plugin.json userConfig

行は mod の名前で始まり、hooks module did not load: options do not fit plugin.json userConfig: と理由が続きます。オプションが userConfig フィールドに対する検証に失敗しています。例えば、フィールドの max を超える数値である場合や、必須フィールドに値がない場合です。

値を設定または変更します。行の末尾は settings.json の pluginConfigs エントリの名前を示します。

code nested too deep to scan: more than 2000 scopes

行は mod の名前で始まり、hooks module did not load:、ファイル、code nested too deep to scan: more than 2000 scopes が続きます。フックモジュール内のファイルは、関数、ブロック、ループなどのスコープを 2,000 階層を超えてネストできません。claude plugin validate も同じ理由を報告します。

スコープのネストが浅くなるようにコードを書き直します。

the engine ran out of stack linking the file and its imports

フックモジュール内のコードのネストが深すぎるか、インポートの連鎖が長すぎるため、Claude Code がそれを読み込めません。行は mod の名前と hooks module did not load: で始まり、ファイルの名前とこの理由が続きます。

そのファイルと、そのファイルのインポートがたどり着くファイルの中で、最も深くネストされているコードを見つけ、ネストが浅くなるように書き直すか、インポートの連鎖を短くしてください。その mod を自分で作成していない場合は、作成者に修正を依頼してください。

the parser stopped または the engine ran out of stack loading the file

フックモジュールのあるファイル内のコードのネストが深すぎるため、Claude Code がそのファイルを読み取る際にスタックを使い果たしました。行は mod の名前と hooks module did not load: で始まり、そのファイルの名前と次のいずれかの理由が続きます。

• code nested too deep to scan (the parser stopped: <message>)
• the engine ran out of stack loading the file (code nested too deep): <message>

理由には行番号が示されず、どの種類のコードがネストしているかも示されないため、ファイル内で最も深くネストしている部分を自分で探してください。その部分をネストが浅くなるように書き直します。mod を自分で書いたのではなくインストールした場合は、作成者に書き直しを依頼してください。

初めて開いたディレクトリで mod が読み込まれない

ディレクトリの信頼プロンプトに答えていません。

claude でそのディレクトリで対話型セッションを開始し、開かれる信頼プロンプトを受け入れます。

インストール済みプラグインが読み込まれない

Claude Code を --safe-mode で開始しました。

フラグなしで開始します。

Claude Code がホットリロードを有効にするか尋ねなくなる

対話型セッションで Claude が mod を書いても何も読み込まれず、Claude Code がホットリロードを有効にするかどうかを再度尋ねません。回答が選択されないまま質問が 3 回終了すると、ホットリロードはオフのままになります。例えば、askUserQuestionTimeout を設定していて、回答する前に時間が経過すると、質問はそのように終了します。Claude Code は AskUserQuestion が使用するのと同じ質問ダイアログで尋ねるため、この設定がここで適用されます。自分で閉じた質問は 3 回には数えられません。

mod を実行するには、mods フォルダからそのディレクトリをコピーし、シェルで --plugin-dir を使用して新しいセッションを開始します（例: claude --plugin-dir ~/mods/git-branch）。

hooks がスキップされるか mod がアンロードされる

mod が読み込まれ、その後 Claude Code がそのいずれかの hooks をスキップするか、アンロードしました。

hook skipped

行は mod とイベントの名前を示し、hook skipped: と理由を示します。例えば first-mod: tool.call hook skipped: threw Error: boom のようになります。フックが例外をスローした、制限時間を超過した、または間違った形状の結果を返しました。行は mod がリロードされるまで、イベントと失敗の種類ごとに 1 回表示されます。

エラーを修正します。デバッグログには発生するたびに行があります。

no command.run hook answered it

mod が追加したコマンドを実行すると、返信は mod とコマンドの名前を示します。例えば first-mod registered /tally but no command.run hook answered it のようになり、hook を追加するよう指示します。Claude Code はコマンドがチェーンの終わりに到達して答えがない場合にその返信を出力します。これは 2 つのケースで発生します。

• hook がコマンドに答えなかった: モジュールに command.run hook がない、hook の filter が別のコマンドを指定している、または hook が next(e) を返した
• Claude Code が hook をスキップした: hook skipped が理由を列挙します。$.ui.open に focus: false を渡すことは、そこに到達する 1 つの方法です。

モジュールが既に返信が説明する hook を持っている場合、command.run という名前の hook skipped 行を探してください。これが理由を示します。コマンドを実行する test は同じ理由で失敗します。

it crashed the hooks worker

行は mod の名前で始まります。例えば first-mod was unloaded: it crashed the hooks worker のようになります。インストール済み mod は 1 つのワーカースレッドを共有します。ワーカーが応答を停止するか、クラッシュし、Claude Code がそれをこの mod に追跡して、アンロードしました。スレッドをブロックする hooks。例えば、await しないループが 1 つの原因です。

hooks を修正します。

its session.start ran again in a fresh copy

行は mod の名前で始まり、$.prompt.submit、$.command.run、または $.agent.spawn の呼び出しを示します。例えば first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again のようになります。Claude Code が mod のモジュールを再度読み込み（例えばフックワーカーがクラッシュして置き換えられた後など）、新しいコピーの session.start フックが実行されました。行が示す呼び出しは、再度実行される代わりに最初の実行の結果で解決されたため、mod がプロンプトを送信したり、コマンドを実行したり、サブエージェントを開始したりすることが 2 回行われることはありません。フックの残りの部分は通常どおり実行されました。

修正する必要はありません。

v2.1.292 より前では、呼び出しが 2 回目も実行されたため、プロンプトの送信、コマンドの実行、またはサブエージェントの開始が 2 回行われていました。

This mod's change didn't load または the earlier version is no longer running

このセッションで Claude が作成した mod への変更を読み込めませんでした。トランスクリプトの行は mod の名前で始まり、理由で終わります。

• This mod's change didn't load, so the earlier version is still running: <reason>.
• This mod didn't load, and the earlier version is no longer running: <reason>.

Claude はこの行を参照できないため、Claude に修正を依頼する際は、次のメッセージにこの行を貼り付けてください。

$.agent.register refused: the hooks module that made the call is no longer loaded

行は mod の名前で始まります。例えば first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed) のようになり、エージェントは登録されません。mod が呼び出しの前にリロードまたはアンロードされました。リロードではフックモジュールの新しいコピーが読み込まれますが、この呼び出しは古いコピーでまだ実行中のコード（例えばまだ戻っていなかったフック）から行われました。

そのフックが拒否をキャッチしない場合、フックは失敗し、Claude Code はそれをスキップします。読み込まれたままのコピーからエージェントを登録するには、session.start フックで呼び出しを行います。このフックはリロード後、新しいコピーごとに再度実行されます。

mods that run in the hooks worker are off for this session

行は hooks: mods that run in the hooks worker are off for this session: it crashed 3 times と読みます。ワーカーが 3 回停止し、Claude Code が停止を 1 つの mod に追跡できなかったため、組み込みでない mod をすべてアンロードしました。組織がインストールする mod を含みます。この行はすべての対話型セッションのトランスクリプトに到達します。

/reload-plugins を実行してそれらを再度読み込みます。

ツール呼び出しが拒否される

mod が読み込まれ、その hooks が実行され、それが触れたツール呼び出しが拒否されます。

a hook changed this call's input after the model wrote it

自動モードでは、拒否されたツール呼び出しはこの理由を示します。hooks が サーバー側分類器 がレビューした後、ツール呼び出しの入力を変更したため、そのレビューは実行される内容をカバーしません。hooks は mod の tool.call または turn.step hooks、または PreToolUse 設定 hooks である可能性があります。メッセージはどれかを示しません。

メッセージは Claude に記録されたとおりに呼び出しを再度発行するよう指示します。それも拒否された場合、hooks は毎回入力を変更するため、mod または hooks をオフにするか、自動モードを離れて呼び出しを自分で承認します。

[!NOTE]

一部のインタラクティブなターミナルセッションと VS Code セッション では、同じ拒否で a hook changed this call's input after auto mode reviewed it という理由が示されます。その場合、再発行された呼び出しには mod による最初の変更が含まれ、tool.call フックは引き続きその呼び出しに対して実行されますが、それ以上の変更は破棄されます。Claude が返答の中で auto モードが呼び出しを確認できなかった と伝えない限り、mod を変更する必要はありません。

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

tried to lift a deny rule in your settings と the deny rules in your settings could not be checked for this call, so it is refused は両方とも組み込みガードから来ます。

組み込みガードからのメッセージ で確認してください。

ターンを停止した後にトーストが表示される

Stopped: type a message to continue; a mod cannot resume work after Stop

このトーストは、Esc などでターンを停止した後に mod が自ら処理を開始しようとし、Claude Code がそれを許可しなかったことを意味します。修正が必要なものはありません。次のメッセージを送信すると mod は再び処理を開始できるようになり、その処理の一部は自動的に再開されます。mod に期待していた結果が返ってこない場合は、もう一度依頼するか、mod のコマンドを再度実行してください。

mod の作成者である場合は、ユーザーがターンを中断した後の呼び出しとバックグラウンド処理を参照してください。

描画が表示されないか応答しない

mod が読み込まれ、そのペイン、バンド、トースト、またはコントロールが期待どおりに動作しません。

別の mod のバンドが表示され、自分のバンドが表示されない

プロンプトの上にはバンドが 1 つしかなく、すべての mod がそれを共有します。自分の mod より前に 実行される mod が next(e) の結果を含まないツリーを返すと、自分のバンドが置き換えられます。両方のバンドを表示するには、その mod のフックを変更するか、作成者に変更を依頼してください。

• 後続のバンドを残す: 描画する場所を選ぶ の「プロンプトの上のバンド」タブのように、await next(e) の結果をツリー内の Box の子要素に含めます
• ツリーを有効に保つ: その Box や、それを囲む Box に、width、height、minWidth、minHeight、position、top、left、right、bottom、display、overflow の props を指定しないでください

その mod を見つけるには、デバッグログを書き出し、answered ui.render without next() を検索します。other-mod (user) answered ui.render without next() のような行は、next(e) を呼び出さずにツリーを返した mod を示します。この行は 描画箇所 を示さないため、ペインのみの mod が表示されることもあります。next(e) を呼び出してもその結果を破棄する mod については行が出力されないため、自分の mod より前のフックも確認してください。

mod 自身のフックが返したツリーが検証を通らない場合も、その mod のバンドは表示されず、他の mod のバンドは残ります。どの mod が原因か、またその理由を確認するには、デバッグログを書き出し、ui.render hook skipped を検索します。

ペインまたはバンドが空であるか、Claude Code の通常のコンテンツを表示する

フックが返した ツリー が検証を通りませんでした。トランスクリプトまたはデバッグログ の hook skipped の行が、mod と理由を示します。ペイン内の Box についての次の例のようになります。

first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

理由が示す内容を修正してください。理由が途中で切れている場合は、デバッグログを書き出し、a hook returned a tree that does not validate を検索して残りを読んでください。

代わりに、ui.render (Pane) refused: のように描画箇所の名前の直後に refused: と表示される場合は、ui.render の行に refused と表示される を参照してください。

ui.render の行に refused と表示される

ui.render (<site>) refused:、または デバッグログ の ui.render (<site>): the chain settled on a tree that does not validate は、その描画箇所の ツリー が サイズ制限 を超えていることを意味します。どちらの行も 描画箇所 を示し、続いて理由を示します。理由はその制限を示します。

その描画箇所に描画する mod を変更して、ui.render フックがより小さいツリーを返すようにするか、作成者に変更を依頼してください。トランスクリプトの行が hooks で始まる場合は、読み込まれた複数の mod がその描画箇所の ui.render フックを持っているため、それぞれの mod のツリーを確認してください。プロンプトの上のバンドがネストして 32 レベルを超える深さのツリーになる複数の mod の場合、行は次のようになります。

hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

v2.1.307 より前では、refused: の行はどの描画箇所についても検証を通らないツリーを報告し、Pane と AbovePrompt では ; the engine drew its own で終わっていました。これらのリリースでは、理由が示す内容を修正してください。

needs a key、is drawn twice、または key each once

ui.render フックが返すツリー内の要素に有効な key がないか、2 つの要素が同じ key を共有しています。受け取ったメッセージを探してください。

• <Input> needs a key または <Select> needs a key: 要素に key props がないか、key が空であるか、key: 3 のように文字列ではありません。key として空でない文字列を指定してください。
• <Button> needs a key: ボタンの key として空でない文字列を指定します
• is drawn twice; each takes its own key: メッセージが示す種類の 2 つの要素が同じ key を持っています。例えば Input "size" is drawn twice; each takes its own key のようになります。各要素に固有の key を指定してください。
• テスト での press からの key each once: 描画内に、渡した key を持つボタンが複数あります。ラベルが同じで key props のないボタンは、そのラベルを key として共有します。各ボタンに固有の key を指定してください。

ui.render の行に threw while drawn と表示される

その行は 描画箇所 を示し、続いて threw while drawn: とエラーを示します。例えば first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own のようになります。Claude Code は、ui.render フックが返したツリーを描画する際、または フックが next に渡した props から描画箇所を描画する際に、そのエラーに遭遇しました。末尾の the engine drew its own は、その描画箇所に Claude Code の通常のコンテンツが表示されることを意味します。

エラーを読み、その原因となったフック内の値を修正してください。

v2.1.289 より前では、トランスクリプトの行でこのエラーが発生すると、Claude Code exited after an unrecoverable interface error でセッションが終了していました。

the module failed without a message

Client が、throw new Error() のようなメッセージのないエラーで失敗しました。その代わりに表示される行は my-mod: Client client/spinner.js: the module failed without a message のようになります。

Client のコード内で throw している箇所を見つけ、エラーにメッセージを付けてください。そうすると、その行にそのメッセージが表示されます。

v2.1.289 より前では、この行には理由として代わりに Error が表示されていました。

$.ui.open が実行され、ペインが表示されない

呼び出しはユーザーが行ったものから来ておらず、ターミナルは そのペインに必要な幅 より狭いです。

コマンドまたはボタンからペインを開くか、呼び出しの isPlaced 結果を確認します。適切なタイミングでペインを開く を参照してください。

トーストが表示されない

mod がインタラクティブなターミナルセッションで $.ui.toast を呼び出しても、トーストが表示されません。呼び出しが実行されたことを確認するには、デバッグログ で mod の名前とトーストのテキストを含む行を探します。例えば $.ui.toast (first-mod): build finished のような行です。次に、以下のような原因を確認してください。

• 呼び出しの行がない: Claude Code が呼び出しを拒否した理由を示す行を探します。例えば first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000 のような行です。
• ペインがトーストを保留している: 表示中のペインを開く際に、自分の mod または別の mod が holdToasts を渡しています。ペインを閉じると保留が終了します。そのペインが自分のもので、開いたままにしておく必要がある場合は、その $.ui.open 呼び出しから holdToasts を削除し、ペインを開き直してください。
• トーストがプロンプトの下にある: クラシックレンダラー では、プロンプトの下の右側を確認します。そこに表示されるトーストは、右上のボックスではなく、mod の名前で始まる 1 行です。
• mod がより新しいトーストを出した: クラシックレンダラーでは、mod からのより新しいトーストが、表示中または表示待ちのトーストに取って代わることがあります。デバッグログには古いトーストについての別の行があり、表示中だった場合は gave way, cut short、表示されなかった場合は gave way, unseen で終わります。両方のメッセージを表示するには、1 つのトーストにまとめてください。
• トーストが描画されないまま時間切れになった: フルスクリーンレンダリングでは、Claude Code は一度に最大 3 つのトーストしか描画しないため、トーストが描画される前に時間切れになることがあります。デバッグログにはそのトーストについての別の行があり、left the stack, never drawn で終わります。mod が一度に複数のトーストを出す場合は、メッセージを 1 つのトーストにまとめてください。

v2.1.290 より前では、Claude Code は、mod に対して最後に表示したトーストから 2 秒以内に出されたトーストを破棄しており、破棄されたトーストのデバッグログの行には within 2000ms of the last; dropped と表示されていました。

バンドに plugin panel hidden と表示される

バンドが 折りたたまれて います。バンドは、Ctrl+X に続けて Ctrl+A（またはその代わりにバインドしたキー）を押したとき、および フルスクリーンレンダリング では最初の行の [-] をクリックしたときに折りたたまれます。展開するか Claude Code を再起動するまで折りたたまれたままで、その間はホットキーや action バインディングでバンド内のボタンを押すことはできません。

バンドを展開するには、その行に示されたキー（デフォルトでは Ctrl+X に続けて Ctrl+A）を押すか、フルスクリーンレンダリングではその行をクリックします。

ホットキーが何もしない

ペインやバンドにキーボードフォーカスがないか、ボタンが折りたたまれたバンド内にあるか、描画が VS Code 拡張機能内にあり、そこではボタンにホットキーがありません。該当するものを実行してください。

• キーボードフォーカスがない: Ctrl+X を押してから Tab を押すか、フルスクリーンレンダリング ではペインまたはバンドをクリックします。ペインが開いたときにフォーカスを取得するようにするには、コマンドから focus: true を指定して開きます。
• ボタンが折りたたまれたバンド内にある: バンドには ▸ plugin panel hidden で始まる薄い 1 行が表示されます。その行に示されたキー（デフォルトでは Ctrl+X に続けて Ctrl+A）を押して 展開します。
• VS Code 拡張機能内の場合: ボタンをクリックするか、ボタンにフォーカスがある状態で Enter を押します

描画がターミナルで機能し、Desktop アプリや VS Code では機能しない

そのアプリが描画箇所または要素を描画しないか、VS Code 拡張機能が mod に対して何も描画しないセッションです。mod の他のフックは引き続き実行されます。以下の原因を確認してください。

• 描画箇所または要素がそのアプリで描画されない: 描画箇所 の表で描画箇所を、要素 の表で要素を調べます。アプリにない要素については、フック内で e.surface を確認し、アプリが描画できるツリーを返します。
• VS Code 拡張機能が 2.1.299 より古い: チャットパネルは 拡張機能のバージョン 2.1.299 から mod の描画を行います。VS Code の拡張機能ビューでバージョンを確認し、そこで拡張機能を更新してください。
• 拡張機能が 2.1.304 より古く、セッションがフィーチャーフラグを取得しない: 拡張機能を更新するか、代わりに VS Code の統合ターミナルで claude を実行してください。Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry 上のセッションは取得をスキップします。Claude apps gateway セッションなど、取得をスキップするその他のセッションについては、フィーチャーフラグの取得が必要な機能 を参照してください。

編集または値が失われる

mod が実行され、行った変更または保持していた値がありません。

編集が有効にならない

インストールした plugin を編集しています。Claude Code はインストール済みバージョンのキャッシュされたコピーを実行します。

claude --plugin-dir ./first-mod のように、作業コピーを指す --plugin-dir で開発します。保存時にリロードされます。

モジュールがリロードされるときに値がリセットされる

モジュールレベルの変数は各リロード時に再初期化されます。

値を $.state または $.store に保持します。

/clear、/resume、または /branch の後に値がリセットされる

値がリセットされるか、保存された値がデフォルトに置き換わります。これらのコマンドはそれぞれ $.state をデフォルトにリセットし、session.start は再度発火しません。

classic.SessionStart hooks で保存された値を再度読み込みます。

settings.read フックが返すキーが有効にならない

Claude Code 自身の読み取りで権限ルールや env を返しても、そのルールはツール呼び出し時にチェックされず、env エントリは環境変数になりません。どちらも設定ファイルを使用するか、env の場合は $.env.set を使用します。

その他のキーについては、どの mod がどのバージョンから settings.read を受け取るかを確認してから、デバッグログで settings.read を検索し、次のいずれかの行を探します。

どの行もキーについて説明していない場合は、自分の mod より前に実行される mod に、そのキーを変更する settings.read フックがないか確認します。その mod をオフにするか、組織の管理者にオフにするよう依頼します。該当するフックがない場合は、キーを設定ファイルで設定します。

the answer for <key> is no value the key can hold

このデバッグログの行は、settings.read フックが指定されたキーに対して返した値を Claude Code が拒否したことを意味し、拒否されたのはそのキーのみです：

settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

指定のキーに対して返された値が、型や範囲などの点でそのキーのスキーマに適合しませんでした。

• 自分の値がキーのスキーマに適合しない場合: キーの設定リファレンスのエントリが許可する値を返します。
• 自分の値が適合する場合: 適合しない値は他の mod の settings.read フックから返されたものです。その mod を特定するには、mod を 1 つずつオフにする手順に従います。新しいログごとに、refused to the engine の代わりにこの行を検索します。

値が適合しない間、そのキーはいずれかのフックが応答する前に設定ソースからマージされた値を保持します。この行ではそれを設定自身の値（the settings' own value）と呼んでいます。

settings.read: refused to the engine

Claude Code 自身の読み取りが拒否されると、デバッグログにこの行が表示され、Claude Code はすべてのフックの値を破棄します。settings.read フックが { deny: reason } でその読み取りを拒否した場合、行にはそのフックの理由が含まれます。

settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

括弧内の理由を自分のコードで検索します。

• コードに含まれている場合: 自分のフックが読み取りを拒否しました。next.origin が Claude Code 自身の読み取りを示す場合は { value } を返すようにします。
• コードに含まれていない場合: 他の mod を 1 つずつオフにします。組織がデプロイした mod の場合は、その管理者にオフにするよう依頼します。それぞれの後に次を行います。
  1. シェルから claude --debug-file ./settings-read-2.log に続けて、セッション開始時のフラグを指定してセッションを開始します。毎回新しいパスを使用します。
  2. そのファイルで refused to the engine を検索します。行がある場合は、次の mod をオフにします。ない場合は、最後にオフにした mod が読み取りを拒否したので、それをオフのままにします。

他の mod が残っていないのに行が表示され続ける場合は、フックが返すキーを設定ファイルで設定します。読み取りが拒否されている間も、その値は保持されます。

デバッグログを読む

デバッグログには、Claude Code が読み込むまたは拒否するすべてのモジュール、失敗するすべてのフック、拒否するすべての結果の行があります。トランスクリプトに何も表示されない場合は、ここを確認してください。書き込むには、シェルで Claude Code を --debug で開始するか、--debug-file <path> で場所を選択します。

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

別のターミナルで、ファイルをフォローして 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

ログに独自の行を書き込むには、$.ui.log を 2 番目の引数で呼び出します。例えば $.ui.log('message', { to: 'debug' }) のようにします。2 番目の引数がない場合、$.ui.log はトランスクリプトに薄い行を追加します。

--plugin-dir で読み込まれた mod を編集している間、トランスクリプトは mod の名前を示し、そのフックをリストする各リロードの行を表示します。保存がモジュールを破損する場合、行は reload failed, the previous version stays loaded: と理由を示し、Claude Code が次にプラグインをリロードするまで（/reload-plugins を実行したときなど）、最後に機能したバージョンが実行され続けます。

次のステップ

• mod をテストする: セッションに到達する前に問題をキャッチします
• プラグインのトラブルシューティング: mod に固有ではないプラグインのインストールと読み込みに関する問題