SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

Claude Code hooksの仕組みと設定方法

Claude Code hooksはmodelの判断に関係なく実行されます。設定場所、発火するevent、exit status 2でtool callをキャンセルする仕組み、security上の注意点を解説します。

Claude Code hook とは

Claude Code hook は、Claude Code が自身のライフサイクル内の決められた時点で自動的に実行するシェルコマンドです。ここが hook と rules file の違いです。CLAUDE.md 内の指示は助言であり、モデルはコンテキスト内の他の情報と比較して判断します。hook はコードであり、モデルが同意するかどうかに関係なく実行されます。フォーマッタを使うように 2 回指示してもエージェントが実行し続けてスキップするなら、より強い指示は必要ありません。必要なのは hook です。

仕組みは単純です。設定ファイルでイベント名にコマンドを登録します。そのイベントが発生すると、Claude Code はコマンドを実行し、イベントデータを JSON(JavaScript object notation)として標準入力(stdin)に書き込みます。コマンドはそのデータを読み取り、処理を行い、終了ステータスを返します。PreToolUse hook が 2 を返すと、ツールの実行前にツール呼び出しがキャンセルされます。スクリプトが標準エラー出力(stderr)に書いた内容は、その理由としてモデルに渡されます。ただし、hook がブロック判断を含む JSON も出力した場合は、その JSON 内の理由が優先されます。

ここで示すイベント名とフィールド名は、2026 年 11 月 12 日に確認した Claude Code の hooks reference に基づいています。この仕様は頻繁に変わるため、このページを含め、ブログ記事から JSON をコピーする前に、使用するバージョンのリファレンスを確認してください。自分の設定は claude --version で出力できます。

フック設定の保存場所

フックは、設定ファイル内の JSON ブロックです。フックを格納できる場所は 6 つあり、フックの適用範囲は設定ファイルの適用範囲と同じです。

  • ~/.claude/settings.json: 自分のマシン上のすべてのプロジェクト。ほかのユーザーには適用されません。
  • .claude/settings.json: 1 つのプロジェクト。リポジトリにコミットするため、クローンした全員にフックが適用されます。
  • .claude/settings.local.json: 1 つのプロジェクト。自分のマシンにだけ適用されます。
  • 管理ポリシー設定: 組織全体に適用され、管理者が設定します。
  • プラグイン内の hooks/hooks.json: そのプラグインが有効な間だけ有効です。
  • Skill または subagent の frontmatter。Skill のフックは Skill を呼び出した後、セッション終了まで有効です。subagent のフックは、その subagent の実行中に有効です。

これらのファイルにあるフックエントリは、互いに上書きされず、統合されます。プロジェクト設定ファイルのフックはユーザー設定のフックを置き換えず、追加されます。そのため、1 つのイベントに複数のファイルから複数のフックを登録できます。"disableAllHooks": true を設定するとフックは無効になります。ただし、管理ポリシー設定のフックは、管理設定でもその設定が適用されない限り、実行され続けます。

セッション内で /hooks を実行すると、現在登録されているすべてのフックがイベント別に一覧表示されます。各フックのソースファイルと matcher も確認できます。このメニューは読み取り専用です。フックを変更するには、設定ファイルを編集します。通常はファイル監視機能が編集を検出するため、再起動は必要ありません。

Claude Code のフックイベントの種類

フックのリファレンスには、SessionStart から SessionEnd まで、コンパクション、サブエージェント、ワークツリー、設定ファイルに関する合計 33 個のイベントが記載されています。サーバー運用では、そのうちのいくつかが使用されます。

  • PreToolUse: EndConversation を除く、ツール呼び出し実行前のイベントです。このイベントは処理をブロックできます。
  • PostToolUse: EndConversation を除く、ツール呼び出し成功後のイベントです。失敗時には PostToolUseFailure が発生するため、すべての結果を監視する必要があるフックでは両方のイベントが必要です。
  • PermissionRequest: ツール呼び出しに権限の判断が必要なタイミング、つまり承認プロンプトが表示される瞬間に発生します。
  • UserPromptSubmit: プロンプトを送信した際、Claude が処理を開始する前に発生します。フックが正常終了した際の標準出力(stdout)は、プレーンテキストとしてモデルのコンテキストに追加されます。
  • SessionStart および SessionEnd: セッションの開始時と終了時に発生します。SessionStart はコンパクション後にも発生し、その際の matcher 値は compact となります。
  • Stop: Claude が応答を完了した時に発生します。これはタスク完了時ではなく、1 ターンごとに発生します。

matcher をサポートするイベントでは、グループに matcher を含めることで、どの発生時にフックを実行するかを決定できます。ツールイベントの場合、これはツール名でフィルタリングされるため、"Edit|Write" はファイル編集時のみに発生します。matcher は大文字と小文字を区別します。matcher が空の場合は、すべての発生時に実行されます。MCP (model context protocol) サーバーからのツールは mcp__<server>__<tool> という名前になるため、"mcp__github__.*" という matcher を設定すると、特定のサーバーのツールのみを対象とし、それ以外は無視されます。

Stop フックには、作成前に知っておくべき注意点があります。ブロックを行う Stop フックはモデルを再試行させますが、デフォルトでは Claude Code は 8 回連続で継続が発生すると次のブロックを上書きします。このカウントは Claude がツールを呼び出すたびにリセットされます。フック入力の stop_hook_active フィールドを確認し、それが true の場合は exit 0 で終了してください。そうしないと、フックが Claude を無限に再試行させ続ける可能性があります。

フックが標準入力で受け取る内容

Claudeが npm test を実行する際、Bash 上の PreToolUse フックは標準入力から以下の内容を読み取ります。

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

一般的な入力フィールドには session_id、cwd、transcript_path、hook_event_name が含まれます。permission_mode はすべてのイベントで送信されるわけではありません。ツールイベントには tool_name、tool_input、tool_use_id が追加されます。その他のイベントには独自のフィールドが含まれます。UserPromptSubmit は prompt テキストを取得し、SessionStart は startup、resume、clear、compact、または fork の source を取得します。

シェルスクリプト内でこれを読み取るには通常 jq を使用しますが、最小構成のサーバーイメージには含まれていない場合があります。その場合は、UbuntuやDebianであれば sudo apt install -y jq を使用して最初にインストールしてください。

終了ステータスが実行中のツール呼び出しに与える影響

結果は3通りです。

  • 終了ステータス 0 は成功を意味し、ブロックや拒否を含む有効な JSON の決定フィールドが適用されます。PreToolUse において、決定を含まない終了ステータス 0 は承認とはみなされず、通常の権限フローが継続します。UserPromptSubmit、UserPromptExpansion、SessionStart、PostModelSwitch では、プレーンテキストの stdout がモデルのコンテキストに追加されます。その他のほとんどのイベントでは、stdout はデバッグログにのみ出力されます。
  • 終了ステータス 2 は、PreToolUse を含むブロック可能なイベントにおいてアクションをブロックします。JSON 出力にブロックの決定が含まれていない限り、stderr がブロックに伴うメッセージとなります(JSON に理由が含まれる場合はそちらが優先されます)。このメッセージを誰が読み取るかはイベントに依存します。PreToolUse および Stop では、モデルがこれを理由として認識します。UserPromptSubmit および PreModelSwitch では、ユーザーに表示され、モデルのコンテキストには追加されません。ブロック不可能な PostToolUse および PostToolUseFailure では、ブロックは無視されますが、stderr はフィードバックとしてモデルに伝わります。その他のブロック不可能なイベントのほとんどでは、stderr はユーザーにのみ表示されるか、無視されます。Stop、SubagentStop、TaskCompleted およびプラグインの UserPromptSubmit フックにおいて、stdout が空で stderr にファイル不在エラーがある終了ステータス 2 は、非ブロックエラーとして扱われます。
  • その他の終了コード で stdout がプレーンテキストまたは空の場合、通常は非ブロックエラーとなります。トランスクリプトには、Failed with non-blocking status code: というテキストの後に stderr の最初の行を含むフックエラー通知が表示されます。PreToolUse などのイベントでは、フックの失敗がアクションをブロックしない限り、有効な JSON によって結果を決定できます。WorktreeCreate はゼロ以外の終了ステータスで失敗し、WorktreeRemove は終了後にディレクトリが存在する場合にゼロ以外の終了ステータスで失敗します。

ブロックや静観以外の処理を行う場合は、終了ステータス 0 で終了し、JSON オブジェクトを stdout に出力してください。PreToolUse フックは permissionDecision を使用して決定を下します。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" は、権限ルールおよびツールの承認要件が許可する場合にインタラクティブなプロンプトをスキップします。"deny" は呼び出しをキャンセルし、その理由をモデルに送信します。"ask" は確認を要求します。フックごとにいずれかのスタイルを選択してください。終了ステータス 2 と stdout への JSON 決定を混在させた場合、JSON が "allow" と指定していてもブロックが維持されます。

複数のフックが 1 つのイベントに一致する場合、それらは並列で実行されます。プロンプトフックおよびエージェントフックは、同時に実行できる数が 12 に制限されています。あるフックからの deny は、他のフックの実行を停止させません。そのため、ガードレールフックが呼び出しを拒否している間も、ログ記録用フックはログを出力し続けます。PreToolUse の場合、Claude Code は回答をマージし、拒否 (deny)、保留 (defer)、確認 (ask)、許可 (allow) の順で最も制限の強いものを採用します。

例 1: 破壊的なコマンドの実行を事前にブロックする

これを .claude/hooks/block-destructive.sh としてプロジェクトに保存します。

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

実行権限を付与し、.claude/settings.json 内の PreToolUse に登録します。

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

フックが自身の入力でクラッシュすると、onFailure が未設定の場合に通常は「失敗しても許可する(fail open)」挙動となるため、信頼する前に必ず手動でスクリプトをテストしてください。Git Bash を使用しない Windows 環境では、シェル形式の PreToolUse や PermissionRequest コマンドフックが失敗すると、ツール呼び出し自体がブロックされる場合があります。

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

stderr に Blocked by policy: という行が表示され、終了コード 2 が返されるはずです。ls -la のような無害なコマンドを入力すると、出力は何も表示されず、終了コード 0 が返されます。セッション内では、拒否された呼び出しが理由とともにトランスクリプトに記録され、モデルはそのメッセージを読み取って適応します。

この手法には重要な特性があります。PreToolUse フックはパーミッションモードのチェックよりも前に、すべてのパーミッションモードで実行されるため、bypassPermissions 下であっても拒否設定が有効に機能します。これが、プロンプトの制限が緩和される Claude Code の自動モードとパーミッション設定 と併用した場合でも、フックが確実に機能する理由です。

この仕組みの限界を正しく理解してください。コマンド文字列のパターンマッチングは、エージェントの不注意に対するガードレールであり、エージェントの悪意に対する境界線ではありません。同じコマンドでも、grep が検知できない形式で記述される可能性があるためです。厳格なルールは、パーミッションシステムおよびプロセスが実行されるアカウント権限で管理すべきです。

例 2: 編集のたびにフォーマットとリントを実行する

PostToolUse に Edit|Write マッチャーを組み合わせると、いずれかのファイル編集ツールが成功した後に実行されます。これを .claude/hooks/after-edit.sh として保存します。

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Claude にインデントが崩れた関数を Python ファイルに追加させ、そのファイルを開いてみてください。自動的にフォーマットされます。フックが実行されたことはこれで確認できます。フックが成功した場合、会話には何も出力されないためです。

ここでの exit 2 は、何も取り消しません。PostToolUse はツールが実行された後に発火するため、編集内容はどちらにせよディスクに書き込まれます。exit 2 を使う利点は、ruff check の出力がフィードバックとしてモデルに伝わることです。これにより、モデルは次に進むのではなく、直前に導入したエラーを修正します。これが、コミット時に見つかるリントエラーと、エージェントが同じターンで修正するエラーの違いです。

ここでは 2 つのマッチャーの制限が重要になります。Edit|Write はシェルコマンドによって変更されたファイルを検知できません。Claude は頻繁に Bash を介してファイルを書き込むため、この制限は無視できません。呼び出しごとのカバレッジを確保するには、Bash もマッチさせ、スクリプトで git status --porcelain を使用して変更されたファイルをリストアップしてください。ターンごとに 1 回のチェックで十分な場合は、代わりに Stop フックにスキャン処理を記述してください。

例 3: 監査のためにすべてのツール呼び出しをログに記録する

PostToolUse 上の空のマッチャーは、EndConversation を除くすべての成功したツール呼び出しで実行されます。レコードをホームディレクトリ内のファイルではなくシステムジャーナルに送信しても、エージェント自身のシェルからアクセスできなくなるわけではありません。アクセス権はアカウントの権限に依存します。ユーザーは自身のプライベートなユーザー単位のジャーナルを読み取ることができ、root および systemd-journal、adm、または wheel のメンバーはすべてのジャーナルファイルを読み取ることができます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

journalctl -t claude-code -o cat | tail -n 5 を使用して読み戻します。レコードの読み取り権限があれば、EndConversation 以外の成功したツール呼び出しごとに 1 行の JSON が、最新のものが最後になる順序で表示されるはずです。何も表示されない場合は、ジャーナルへのアクセス権とフックが実行されたかどうかを確認してください。以下のトラブルシューティングセクションでフックについて解説しています。

失敗した呼び出しをキャプチャするには、PostToolUseFailure の下に同じブロックを追加してください。PostToolUse は成功時にのみ実行され、通常は失敗したコマンドこそが重要な情報となるためです。ホームディレクトリ内のファイルへの追記ではなく logger を使用する理由は所有権にあります。フックはエージェントのシェルと同じユーザーとして実行されるため、そのユーザーが追記できるファイルであれば、そのユーザーは切り捨てる(truncate)ことも可能です。ジャーナルは systemd-journald によって書き込まれますが、削除からの保護は依然としてエージェントアカウントの権限に依存します。

フックの実行時間制限

グラフDefault hook timeout in seconds, by hook type and event
このグラフのデータ
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

コマンドフックにはデフォルトで 600 秒(10分)が割り当てられます。一部のイベントでは、この時間が大幅に短縮されます。SessionEnd フックは合計で 1.5 秒の予算を共有するため、セッション終了時のクリーンアップは迅速に行う必要があります。ただし、設定ファイルでフックの timeout を長く設定すると、共有予算も最大 60 秒まで引き上げられます。

同期コマンド、HTTP、または MCP ツールフックがタイムアウトに達すると、その処理はキャンセルされ、通常は判定結果を返しません。PreModelSwitch の場合、タイムアウトが発生するとスイッチがブロックされます。PreToolUse ガードレールの場合、タイムアウトが発生しても通常はツール呼び出しがそのまま通常の許可フローへ進みます(onFailure が未設定の場合の Windows での例外を除く)。このため、ガードレールスクリプトは軽量に保ってください。リリース 2.1.295 以降では、command または http フックに対して "onFailure": "block" を指定することで、このデフォルト動作を反転できます。これにより、タイムアウト、クラッシュ、予期しない終了コードが発生した際にブロックするようになります。ただし、この設定は Stop、SubagentStop、TaskCompleted、TeammateIdle、またはバックグラウンドコマンドフックには影響しません。ログの転送など、待機を必要としない低速な処理については、"async": true を設定してください。これにより、フックはツール呼び出しを停止させることなくバックグラウンドで実行されます。

Hooks、rules file、skill、MCP server

これらはすべて agent の動作を変えるため、互いに混同されがちです。ただし、提案として扱われなくなるのは 1 つだけです。

rules file(CLAUDE.md、または .claude/rules/ 配下のファイル)は、model のコンテキストに読み込まれるテキストです。動作を方向付けますが、強制はしません。長い会話、大きな差分、新しい user request が重なると、その 1 行が無視されることがあります。これは、記述した指示を agent が無視する一般的な仕組みです。

skill は、model が関連性を判断したときに読み込む指示とスクリプトのフォルダーです。その判断こそが skill の目的であり、同時に限界でもあります。最終的には model が決定します。Ponytail は agent に実用上最小限の変更を促すskill の好例です。hook では実現できない方法でタスク全体への取り組み方を方向付けられますが、model が読み込むことを選択した場合に限られます。

MCP(model context protocol)server は、model が呼び出せる新しいツールを提供します。これにより agent がアクセスできる範囲が広がります。ただし、agent にそのツールを使わせるわけではありません。また、別プロセスとして運用する必要があり、それ自体が独立した作業になります。詳しくは VPS での MCP server の運用を参照してください。

4 つの中で、model の選択なしに実行されるのは hook だけです。好みを指定する場合は rules file を、適用時に model が従うべき手順を指定する場合は skill を使います。毎回必ず実行する必要がある処理や、決して実行してはならない処理には hook を使います。skill が rules file より適する場合を含む詳しい比較は、skill、MCP、rules file の比較で説明しています。

plugin は 5 つ目の仕組みではなく、パッケージ化の単位です。hook と skill を 1 つのインストール可能な単位にまとめます。これにより、チームは同じガードレールをすべてのマシンに導入できます。詳しくは Claude Code plugin の仕組みを参照してください。

共有 VPS でのセキュリティ判断

hook はエージェントが起動するコードであり、Claude Code を起動したユーザーとして実行されます。そのユーザーのファイル権限と環境を引き継ぎます。ラップトップではワークフロー上の問題です。エージェントを無人で実行する VPS では、実際の運用上、4 つの観点からセキュリティ上の問題になります。

リポジトリ内の hook は、自分が作成していないコードです。 .claude/settings.json はコミットされるため、リポジトリを clone してその中でセッションを開始すると、リポジトリに含まれる hook が登録されることがあります。対話型セッションでは、Claude Code はそのフォルダのワークスペース信頼ダイアログを通じてプロジェクト hook の実行を制御します。つまり、信頼を受け入れることが、hook の実行を許可する判断になります。先に hooks ブロックを読んでください。無人エージェントで通常使用する claude -p または SDK セッションでは、このダイアログは表示されません。フォルダは信頼済みとして扱われるため、リポジトリの hook は確認なしで実行されます。スクリプトから利用する前に .claude/ ファイルを確認するか、--settings '{"disableAllHooks": true}' を指定して実行してください。

hook はツール入力全体を参照できます。 tool_input を記録する監査 hook は、すべてのコマンドの全引数をログに書き込みます。コマンドライン上に偶然存在したトークンも含まれます。そのログにも Secret と同じ保護が必要です。これは、AI エージェントの手の届く範囲から Secret を排除するという、より広い問題の一部です。

hook はモデルのコンテキストに書き込めます。 成功した SessionStart または UserPromptSubmit hook のプレーンテキストの stdout は会話に追加されます。外部、Issue Tracker、ログファイルなどからテキストを取り込む hook は、ユーザーが自分で入力したかのように、信頼できないテキストをモデルへ渡します。同じ VPS 上の別の Claude Code セッションからメモを転送する hook も同じです。あるエージェントの出力が Issue Tracker の内容より信頼できるとは限りません。その stdout は出力ではなく入力として扱ってください。

実際の制御は権限です。 エージェントは、必要な sudo ルールだけを持つ専用の非特権ユーザーとして実行してください。PreToolUse deny を設定する価値はあります。ただし、これは設計上ベストエフォートです。リファレンスは if filter についても同様に説明し、強制的に deny する必要がある場合は permission system を使うよう指示しています。厳しい状況でも有効な要素は、permission rules とプロセスの実行アカウントです。

どの permission mode でも成立する性質が 1 つあります。PreToolUse hook は、すべての permission mode で permission-mode check より前に実行されます。そのため、deny を返す hook は bypassPermissions でもツールをブロックします。hook によって、permission rules が許可する操作をさらに制限できます。緩和することはできません。例外は mod です。managed settings がなく、managed-mcp.json ファイルもないマシンで、Team または Enterprise plan に /login 経由でサインインしていないセッションでは、tool.check を処理するインストール済みの mod が、PreToolUse hook によってブロックされた呼び出しを承認できます。managed settings、managed-mcp.json ファイル、またはセッションの認証情報として Team または Enterprise /login がある場合、PreToolUse hook がブロックした呼び出しは、hook がどの設定ファイルに由来するかに関係なく、デフォルトでブロックされたままです。API key または長期的な CLAUDE_CODE_OAUTH_TOKEN で実行するセッションは、多くのサーバーでの実行方法ですが、ログイン情報が保存されていても未サインインとして扱われます。サーバーに mod をインストールする前に、Claude Code mod で変更できる内容を確認してください。

なぜフックが実行されないのですか?

以下の手順を順番に確認してください。各ステップには、実際に発生する症状を記載しています。

  • /hooks を実行し、期待するイベントの下にフックが表示されているか確認してください。メニューにフックが表示されない場合、設定ファイルに JSON 構文エラーがある可能性が高いです。末尾のカンマやコメントは許可されておらず、またファイルが上記の6つの場所のいずれにも存在しない場合も同様です。
  • マッチャーとツール名を正確に比較してください。マッチャーは大文字と小文字を区別するため、"bash" は Bash ツールには一致しません。
  • 上記の例1のように、サンプル入力を使用して手動でスクリプトを実行してください。予期しない終了コードが返される場合はスクリプトのバグです。stdout も確認してください。有効な JSON であっても、PreToolUse などのイベントに対して決定を下す可能性があるためです。
  • jq: command not found という通知が表示される場合、そのマシンに jq が存在しません。自身のスクリプトで command not found が発生する場合はパスが解決できていないため、${CLAUDE_PROJECT_DIR} または絶対パスを使用してください。スクリプトが全く実行されない場合は、実行権限が付与されていない可能性があります。
  • フックが有効な JSON を出力しても何も起こらない場合。macOS および Linux では、シェル形式のフックは非対話型シェルで sh -c を介して実行されますが、BASH_ENV が ~/.bashrc を指している場合など、環境によってはプロファイルが読み込まれることがあります。そのプロファイルがバナーを出力すると、JSON の先頭にバナーが付加されます。Stdout が { で始まらなくなるため、Claude Code は全体をプレーンテキストとして読み込み、決定を無視します。フックは終了コード 0 で終了するため、トランスクリプトにはエラーが表示されません。ほとんどのイベントではそのテキストはデバッグログにのみ記録されますが、UserPromptSubmit、UserPromptExpansion、SessionStart、PostModelSwitch の場合はバナーを含めてモデルのコンテキストに追加されます。プロファイル内の echo は、対話型シェルでのみ実行されるようにラップしてください。
  • それでも解決しない場合:claude --debug-file /tmp/claude.log でセッションを開始し、別のターミナルで tail -f /tmp/claude.log を実行してください。デバッグログには、どのフックが一致したか、各フックが返した終了コード、および stdout と stderr に書き込まれたすべての内容が記録されます。

FAQ

Claude Code のフックと CLAUDE.md の指示にはどのような違いがありますか?

CLAUDE.md 指示はモデルのコンテキストに含まれるテキストであるため、会話や現在のリクエストと注意力を奪い合い、モデルがそれらを比較検討する可能性があります。一方、フックは Claude Code がライフサイクルの特定のタイミングで実行するシェルコマンドであり、モデルの判断に関わらず、イベントが発生するたびに必ず実行されます。好みを伝えるには指示を、必ず実行すべき手順や決して実行してはならないアクションにはフックを使用してください。

特定のシェルコマンドを Claude Code が実行しないようにするにはどうすればよいですか?

PreToolUse フックを登録し、Bash マッチャーを使用して .tool_input.command からコマンドを読み取り、理由を stderr に出力して 2 で終了するように設定します。Claude Code は呼び出しをキャンセルし、モデルにその理由を表示します。これは権限モードのチェック前に行われるため、bypassPermissions モードであっても拒否が適用されます。コマンド文字列のパターンマッチングはガードレールであり、セキュリティ境界ではありません。同じコマンドでもパターンをすり抜ける形式で記述できる可能性があるため、権限ルールや非特権アカウントによる制限を併用してください。

フックが正しい JSON を出力しているのに何も起こりません。なぜですか?

シェルプロファイルで JSON の前にテキストが出力されていないか確認してください。macOS や Linux では、args フィールドのないフックは sh -c を経由して実行されます。BASH_ENV が ~/.bashrc を指しているような環境でプロファイルを読み込む設定になっていると、バナーを出力するプロファイルが JSON よりも先に stdout へ書き込んでしまいます。出力が { で始まらなくなるため、Claude Code はすべてをプレーンテキストとして扱い、判断を無視します。フックは 0 で終了するため、トランスクリプトにはエラーが表示されません。プロファイル内の echo は対話型シェルテストで保護し、claude --debug-file /tmp/claude.log からデバッグログを読み取って修正を確認してください。

共有サーバーで Claude Code のフックを実行しても安全ですか?

フックは Claude Code を起動したユーザーとして、そのユーザーのファイル権限で実行されるため、そのアカウントで可能なことはすべて実行できてしまいます。リスクを抑えるには 2 つの習慣が有効です。エージェントを制限された sudo ポリシーを持つ専用の非特権アカウントで実行すること、そしてリポジトリのワークスペース信頼ダイアログを承認したり claude -p を実行したりする前に、リポジトリの hooks ブロックを確認することです。プロジェクトフックは .claude/settings.json 内に含まれており、-p モードではダイアログが表示されないためです。設定ファイルで "disableAllHooks": true を設定するとフックを無効化できますが、管理レベルで設定が必要な管理対象フックは例外です。false というプロジェクト設定は、true というユーザー設定を上書きする可能性があります。

この記事は役に立ちましたか?