読み込み中
読み込み中

フック

CLAUDE.mdファイルでClaudeに何かをするよう指示することには、ひとつ問題があります。 それはリクエストであって、保証ではないということです。「編集後は必ずフォーマットする」 と書けば、Claudeは通常それに従います。通常は。しかし、長時間実行していて見ていないとき には、「通常は」では十分ではありません。フックはそれを解決します。フックはループ内の 決まった時点で実行される決定論的なコードであり、動作を期待するのではなく保証できます。 これにより、「Claudeは通常従う」というルールが「Claudeはスキップできない」という ルールに変わります。

これが要点のすべてです。では、実際にどう機能するのか見ていきましょう。

フックイベント

Claude Codeは、セッションの過程で約30のフックイベントを発生させます。そのすべてを知る必要はありません。フックリファレンスにすべてが記載されています。何度も繰り返し使うことになる一握りのものがあり、それらはエージェントループの中で介入したくなるポイントに対応しています。

それらがループの中でどのように位置づけられるかを見てみましょう。セッションが開始し、プロンプトが入ってきて、ツールが呼び出され、やがてターンが終了します。それぞれの瞬間に、コードを紐づけられるフックが存在します。

知っておく価値があるものは次のとおりです。

  • PreToolUse はツール呼び出しの前に発生します。これが強制の基本要素です。何かが起こる前に止めることができる唯一のものです。
  • PostToolUse はツール呼び出しが成功した後に発生します。通常、自動フォーマットや自動lintはここに配置します。
  • Stop はClaudeがターンを終了しようとするときに発生します。ある条件が満たされていなければ、「いや、まだ終わっていません」と拒否できます。サブエージェントが終了する際に対応するSubagentStopもあります。
  • PreCompact と PostCompact は、コンテキスト圧縮の前後に発生します。
  • InstructionsLoaded はCLAUDE.mdやルールファイルが読み込まれるときに発生します。実際にコンテキストに取り込まれた内容を監査するのに便利です。
  • SessionStart は開始時に発生し、環境を準備します。新規開始時のみ使いたい場合は、startup ソースを使用してください。

ひとつ、つまずきやすい点があります。コンテキスト圧縮後にコンテキストを再注入するには、PostCompactを使わないでください。compact マッチャーを指定した SessionStart を使用します。これが、実際に出力を会話に戻してくれるものです。

PreToolUse: JSONとして判定を返す

PreToolUseこそが真の力を発揮する場所です。なぜなら、ツール呼び出しが実行される前にブロックできるからです。Claudeに応答する方法は、JSONを出力して終了コード0で終了することです。キーとなるフィールドは permissionDecision で、次の3つの値のいずれかを取ります。

  • allow — 呼び出しを通過させる
  • deny — 呼び出しを止める
  • ask — ユーザーに判断を委ねる

技術的には4つ目の値 defer もありますが、これは呼び出し元のプロセスがツールを一時停止し、後で再開する非対話型の -p 実行にのみ適用されます。これを使うことはめったにないでしょう。

形はこのようになります。

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Don't push to main. Open a pull request instead."
  }
}

呼び出しをブロックする代わりに、書き換えることもできます。updatedInput とともに allow または ask を返します。ask の場合、書き換えられた呼び出しを確認してから承認します。allow の場合、プロンプトなしで実行されます。

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "updatedInput": {
      "command": "..."
    }
  }
}

これが、bashコマンドからシークレットを秘匿しつつ実行させる方法です。ひとつ注意点があります。updatedInput は入力オブジェクト全体を置き換えるため、変更しないフィールドもそのまま返す必要があります。そうしないと失われてしまいます。

終了コード:JSONを返さないフック向け

すべてのフックがJSONを返す必要はありません。よりシンプルなフックでは、終了コードで十分です。重要な数字は3つあります。

  • 0は成功です。 標準出力がJSONであれば、Claudeはそれをパースします。プレーンテキストはほとんどのイベントで無視されますが、SessionStart、UserPromptSubmit、UserPromptExpansionでは、プレーンテキストがコンテキストに追加されます。これこそが、状態保持フックを機能させている仕組みです。
  • 2はブロッキングエラーです。 標準エラーがコンテキストとしてClaudeにフィードバックされます。これはほぼどこでもブロッキングの終了コードです。
  • それ以外はすべて非ブロッキングです。標準エラーはログに記録され、Claudeはそのまま続行します。

人をつまずかせるのが終了コード1です。エラーのように感じられますが、ブロックはしません。Claudeはともかくコマンドを実行します。そのため、何かを止めたいのであれば、1ではなく2で終了してください。

もういくつか注意点があります。終了コード2はStopさえもブロックでき、これがClaudeに「まだ終わっていない」と伝える方法です。しかし、PostToolUseはツールがすでに実行された後に発生するため、そこでブロックしても呼び出しを止めるには遅すぎます。ただし、テキストをClaudeにフィードバックすることはまだ可能です。また、NotificationやSessionStartのように、ブロッキングを完全に無視するイベントもいくつかあります。SessionStartは標準エラーをあなたにのみ表示し、Notificationはそれを無視し、どちらもそのまま続行します。

実際のガードレール:ブロックの代わりに秘匿する

実践的な例でまとめてみましょう。Bashツールに対してPreToolUseのガードレールを設定したいとします。設定ファイルにフックを登録します。これを .claude/settings.json に入れてコミットすれば、チームで共有できます。

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

matcher は監視対象のツールを指定し、フックのオプションの if フィールドを使えば、"if": "Bash(curl *)" のように特定のコマンドに絞り込むことができます。/hooks を実行して、フックが登録されていることを確認してください。

分かりやすい方法は deny を返して危険な呼び出しを止めることです。それも良いでしょう。しかし、あまり知られていないもののより興味深い方法は、updatedInput を返して呼び出しを書き換えることです。これが、単に拒否するのではなく、コマンドからシークレットを取り除きつつ実行させる方法です。

実際にどう見えるか見てみましょう。Claudeは、本番環境のように見えるシークレットを含むコマンドの実行を求められます。フックがそれをインターセプトし、sk_live_ というパターンを検出して、コマンドが実行される前にプレースホルダーに置き換えます。

こちらがスクリプト .claude/hooks/redact-secrets.sh です。jq が必要で、chmod +x で実行可能にします。

bash
#!/bin/bash
# コマンド実行前に、本物らしく見えるキーを置き換えます。
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Replaced a live key with a placeholder",
    updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
  }
} else empty end'

これは ask を返すため、書き換えられたコマンドを承認します。allow を返すと、パターンに一致するすべてのコマンドでそのプロンプトがスキップされてしまいます。承認すると、コマンドはシークレットなしで実行されます。これがブロックと秘匿の違いであり、フックが毎回確実に強制できる類のものです。

コンテキスト圧縮をまたいで状態を保持する

もうひとつ、設定しておく価値のあるパターンがあります。Claudeが長い会話をコンテキスト圧縮すると、多くの詳細が失われます。compact マッチャーを指定した SessionStart フックは、コンテキスト圧縮の直後に実行されます。作業中のファイルの簡単な要約を出力させましょう。その要約はコンテキストに戻されるため、Claudeはゼロから始めるのではなく、中断したところから再開できます。これは未コミットの変更を一覧表示する例です。

json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git status --short" }]
      }
    ]
  }
}

まとめ

フックは、Claudeが通常従うルールを、常に従うルールに変えます。自動フォーマットにとどまらず、PreToolUseでツールを保護し、Stopでターンをゲートし、コンテキスト圧縮をまたいで状態を保持しましょう。設定には最初に少し手間がかかりますが、見ていなかった実行で何かを検知できた瞬間に、その手間は報われます。