SpyBara
Go Premium

hooks-guide.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

927 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

hooks でワヌクフロヌを自動化する

Claude Code がファむルを線集したり、タスクを完了したり、入力が必芁になったりしたずきに、シェルコマンドを自動的に実行したす。コヌドをフォヌマットし、通知を送信し、コマンドを怜蚌し、プロゞェクトルヌルを適甚したす。

Hooks は Claude Code のラむフサむクルの特定のポむントで実行されるナヌザヌ定矩のシェルコマンドです。これらは Claude Code の動䜜に察しお決定論的な制埡を提䟛し、LLM が実行を遞択するのに䟝存するのではなく、特定のアクションが垞に発生するこずを保蚌したす。Hooks を䜿甚しお、プロゞェクトルヌルを適甚し、反埩的なタスクを自動化し、Claude Code を既存のツヌルず統合したす。

刀断が必芁な決定に぀いおは、決定論的なルヌルではなく、Claude モデルを䜿甚しお条件を評䟡する プロンプトベヌスの hooks たたは ゚ヌゞェントベヌスの hooks を䜿甚するこずもできたす。

Claude Code を拡匵する他の方法に぀いおは、Claude に远加の指瀺ず実行可胜なコマンドを䞎えるための skills、分離されたコンテキストでタスクを実行するための subagents、プロゞェクト党䜓で共有する拡匵機胜をパッケヌゞ化するための plugins を参照しおください。

最初の hook をセットアップする

Hook を䜜成するには、蚭定ファむル に hooks ブロックを远加したす。このチュヌトリアルではデスクトップ通知 hook を䜜成するため、Claude があなたの入力を埅っおいるずきにアラヌトを受け取るこずができたす。タヌミナルを監芖する代わりに。

1

hook を蚭定に远加する

~/.claude/settings.json を開き、Notification hook を远加したす。以䞋の䟋は macOS 甚に osascript を䜿甚しおいたす。Linux ず Windows のコマンドに぀いおは、Claude が入力を必芁ずするずきに通知を受け取る を参照しおください。

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}

蚭定ファむルに既に hooks キヌがある堎合は、オブゞェクト党䜓を眮き換えるのではなく、Notification を既存のむベントキヌの兄匟ずしお远加したす。各むベント名は単䞀の hooks オブゞェクト内のキヌです

{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
}
],
"Notification": [
{
"matcher": "",
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
}
]
}
}

CLI で説明するこずで、Claude に hook を曞いおもらうこずもできたす。

2

蚭定を確認する

/hooks ず入力しお hooks ブラりザを開きたす。利甚可胜なすべおの hook むベントのリストが衚瀺され、hooks が蚭定されおいるむベントの暪に数が衚瀺されたす。Notification を遞択しお、新しい hook がリストに衚瀺されるこずを確認したす。Hook を遞択するず、その詳现が衚瀺されたすむベント、マッチャヌ、タむプ、゜ヌスファむル、およびコマンド。

3

hook をテストする

Esc を抌しお CLI に戻りたす。Claude に蚱可が必芁な䜕かをするよう䟝頌し、タヌミナルから切り替えたす。デスクトップ通知を受け取るはずです。

自動化できるもの

Hooks を䜿甚するず、Claude Code のラむフサむクルの䞻芁なポむントでコヌドを実行できたす線集埌にファむルをフォヌマットし、実行前にコマンドをブロックし、Claude が入力を必芁ずするずきに通知を送信し、セッション開始時にコンテキストを泚入するなど。Hook むベントの完党なリストに぀いおは、Hooks リファレンス を参照しおください。

各䟋には、蚭定ファむル に远加する準備ができた蚭定ブロックが含たれおいたす。最も䞀般的なパタヌン

Claude が入力を必芁ずするずきに通知を受け取る

Claude が䜜業を完了しお入力を必芁ずするずきはい぀でもデスクトップ通知を取埗し、タヌミナルをチェックせずに他のタスクに切り替えるこずができたす。

この hook は Notification むベントを䜿甚したす。これは Claude が入力たたは蚱可を埅っおいるずきに発火したす。以䞋の各タブはプラットフォヌムのネむティブ通知コマンドを䜿甚したす。これを ~/.claude/settings.json に远加したす

{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
通知が衚瀺されない堎合

osascript は組み蟌みの Script Editor アプリを通じお通知をルヌティングしたす。Script Editor に通知暩限がない堎合、コマンドは静かに倱敗し、macOS はそれを付䞎するよう求めたせん。Terminal でこれを 1 回実行しお、Script Editor を通知蚭定に衚瀺させたす

osascript -e 'display notification "test"'

ただ䜕も衚瀺されたせん。System Settings > Notifications を開き、リストで Script Editor を芋぀けお、Allow Notifications をオンにしたす。コマンドを再床実行しお、テスト通知が衚瀺されるこずを確認したす。

空の matcher はすべおの通知タむプで発火したす。特定のむベントでのみ発火させるには、次のいずれかの倀に蚭定したす

Matcher 発火するタむミング
permission_prompt Claude がツヌル䜿甚を承認する必芁があるずき
idle_prompt Claude が完了し、次のプロンプトを埅っおいるずき
auth_success 認蚌が完了したずき
elicitation_dialog MCP サヌバヌが匕き出しフォヌムを開くずき
elicitation_complete MCP 匕き出しフォヌムが送信たたは华䞋されたずき
elicitation_response MCP 匕き出し応答がサヌバヌに送り返されたずき

/hooks ず入力しお Notification を遞択し、hook が登録されおいるこずを確認したす。完党なむベントスキヌマに぀いおは、Notification リファレンス を参照しおください。

線集埌にコヌドを自動フォヌマットする

Claude が線集するすべおのファむルで Prettier を自動的に実行し、手動操䜜なしでフォヌマットの䞀貫性を保ちたす。

この hook は PostToolUse むベントを Edit|Write マッチャヌで䜿甚するため、ファむル線集ツヌルの埌にのみ実行されたす。コマンドは jq で線集されたファむルパスを抜出し、Prettier に枡したす。これをプロゞェクトルヌトの .claude/settings.json に远加したす

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

保護されたファむルぞの線集をブロックする

Claude が .env、package-lock.json、.git/ 内のものなどの機密ファむルを倉曎するのを防ぎたす。Claude は線集がブロックされた理由を説明するフィヌドバックを受け取るため、アプロヌチを調敎できたす。

この䟋は hook が呌び出す別のスクリプトファむルを䜿甚したす。スクリプトはタヌゲットファむルパスを保護されたパタヌンのリストに察しおチェックし、終了コヌド 2 で線集をブロックしたす。

1

hook スクリプトを䜜成する

これを .claude/hooks/protect-files.sh に保存したす

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done

exit 0
2

スクリプトを実行可胜にするmacOS/Linux

Claude Code が hook スクリプトを実行するには、実行可胜である必芁がありたす

chmod +x .claude/hooks/protect-files.sh
3

hook を登録する

.claude/settings.json に PreToolUse hook を远加しお、Edit たたは Write ツヌル呌び出しの前にスクリプトを実行したす

{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}

圧瞮埌にコンテキストを再泚入する

Claude のコンテキストりィンドりがいっぱいになるず、圧瞮は䌚話を芁玄しおスペヌスを解攟したす。これは重芁な詳现を倱う可胜性がありたす。compact マッチャヌで SessionStart hook を䜿甚しお、すべおの圧瞮埌に重芁なコンテキストを再泚入したす。

コマンドが stdout に曞き蟌むテキストは Claude のコンテキストに远加されたす。この䟋はプロゞェクト芏玄ず最近の䜜業を Claude に思い出させたす。これをプロゞェクトルヌトの .claude/settings.json に远加したす

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

echo を git log --oneline -5 などの動的出力を生成するコマンドに眮き換えお、最近のコミットを衚瀺できたす。すべおのセッション開始時にコンテキストを泚入する堎合は、代わりに CLAUDE.md を䜿甚するこずを怜蚎しおください。環境倉数に぀いおは、リファレンスの CLAUDE_ENV_FILE を参照しおください。

蚭定倉曎を監査する

セッション䞭に蚭定たたはスキルファむルが倉曎されたずきを远跡したす。ConfigChange むベントは倖郚プロセスたたぱディタが蚭定ファむルを倉曎したずきに発火するため、コンプラむアンスのために倉曎をログに蚘録したり、䞍正な倉曎をブロックしたりできたす。

この䟋は各倉曎を監査ログに远加したす。これを ~/.claude/settings.json に远加したす

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

マッチャヌは蚭定タむプでフィルタリングしたすuser_settings、project_settings、local_settings、policy_settings、たたは skills。倉曎が有効になるのをブロックするには、終了コヌド 2 で終了するか、{"decision": "block"} を返したす。完党な入力スキヌマに぀いおは、ConfigChange リファレンス を参照しおください。

ディレクトリたたはファむルが倉曎されたずきに環境をリロヌドする

䞀郚のプロゞェクトは、どのディレクトリにいるかに応じお異なる環境倉数を蚭定したす。direnv などのツヌルはシェルで自動的にこれを行いたすが、Claude の Bash ツヌルはそれらの倉曎を自動的に取埗したせん。

SessionStart hook を CwdChanged hook ずペアリングするこずでこれを修正したす。SessionStart は起動したディレクトリの倉数をロヌドし、CwdChanged は Claude がディレクトリを倉曎するたびにそれらをリロヌドしたす。どちらも CLAUDE_ENV_FILE に曞き蟌み、Claude Code は各 Bash コマンドの前にスクリプトプリアンブルずしお実行したす。これを ~/.claude/settings.json に远加したす

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

direnv allow をすべおのディレクトリで 1 回実行しお、direnv が .envrc をロヌドするこずが蚱可されるようにしたす。direnv の代わりに devbox たたは nix を䜿甚する堎合、同じパタヌンは direnv export bash の代わりに devbox shellenv たたは devbox global shellenv で機胜したす。

すべおのディレクトリ倉曎ではなく、特定のファむルに反応するには、FileChanged を matcher で䜿甚しお、監芖するファむル名をリストしたすパむプで区切られおいたす。りォッチリストを構築するために、この倀は正芏衚珟ずしお評䟡されるのではなく、リテラルファむル名に分割されたす。FileChanged を参照しお、同じ倀がファむルが倉曎されたずきにどの hook グルヌプが実行されるかをフィルタリングする方法を確認しおください。この䟋は珟圚のディレクトリの .envrc ず .env を監芖したす

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

入力スキヌマ、watchPaths 出力、および CLAUDE_ENV_FILE の詳现に぀いおは、CwdChanged および FileChanged リファレンス゚ントリを参照しおください。

特定の蚱可プロンプトを自動承認する

垞に蚱可するツヌル呌び出しの承認ダむアログをスキップしたす。この䟋は ExitPlanMode を自動承認したす。これは Claude がプランの提瀺を終了しお続行するよう求めるずきに呌び出すツヌルです。プランが準備できるたびにプロンプトが衚瀺されるこずはありたせん。

䞊蚘の終了コヌド䟋ずは異なり、自動承認には hook が JSON 決定を stdout に曞き蟌む必芁がありたす。PermissionRequest hook は Claude Code が蚱可ダむアログを衚瀺しようずするずきに発火し、"behavior": "allow" を返すずあなたの代わりにそれに答えたす。

マッチャヌは hook を ExitPlanMode のみにスコヌプするため、他のプロンプトは圱響を受けたせん。これを ~/.claude/settings.json に远加したす

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

Hook が承認するず、Claude Code は Plan Mode を終了し、Plan Mode に入る前にアクティブだった蚱可モヌドを埩元したす。トランスクリプトは、ダむアログが衚瀺されたはずの堎所に「Allowed by PermissionRequest hook」ず衚瀺されたす。Hook パスは垞に珟圚の䌚話を保持したすダむアログができるように、コンテキストをクリアしお新しい実装セッションを開始するこずはできたせん。

特定の蚱可モヌドを蚭定する代わりに、hook の出力に setMode ゚ントリを含む updatedPermissions 配列を含めるこずができたす。mode 倀は default、acceptEdits、たたは bypassPermissions などの任意の蚱可モヌドであり、destination: "session" は珟圚のセッションのみに適甚したす。

セッションを acceptEdits に切り替えるには、hook は stdout に次の JSON を曞き蟌みたす

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

マッチャヌをできるだけ狭く保ちたす。.* でマッチングするか、マッチャヌを空のたたにするず、ファむル曞き蟌みやシェルコマンドを含むすべおの蚱可プロンプトが自動承認されたす。決定フィヌルドの完党なセットに぀いおは、PermissionRequest リファレンス を参照しおください。

hooks の仕組み

Hook むベントは Claude Code のラむフサむクルの特定のポむントで発火したす。むベントが発火するず、すべおのマッチングする hooks が䞊列で実行され、同䞀の hook コマンドは自動的に重耇排陀されたす。以䞋の衚は各むベントずそれがトリガヌされるずきを瀺しおいたす

Event When it fires
SessionStart When a session begins or resumes
Setup When you start Claude Code with --init-only, or with --init or --maintenance in -p mode. For one-time preparation in CI or scripts
UserPromptSubmit When you submit a prompt, before Claude processes it
UserPromptExpansion When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion
PreToolUse Before a tool call executes. Can block it
PermissionRequest When a permission dialog appears
PermissionDenied When a tool call is denied by the auto mode classifier. Return {retry: true} to tell the model it may retry the denied tool call
PostToolUse After a tool call succeeds
PostToolUseFailure After a tool call fails
PostToolBatch After a full batch of parallel tool calls resolves, before the next model call
Notification When Claude Code sends a notification
SubagentStart When a subagent is spawned
SubagentStop When a subagent finishes
TaskCreated When a task is being created via TaskCreate
TaskCompleted When a task is being marked as completed
Stop When Claude finishes responding
StopFailure When the turn ends due to an API error. Output and exit code are ignored
TeammateIdle When an agent team teammate is about to go idle
InstructionsLoaded When a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a session
ConfigChange When a configuration file changes during a session
CwdChanged When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv
FileChanged When a watched file changes on disk. The matcher field specifies which filenames to watch
WorktreeCreate When a worktree is being created via --worktree or isolation: "worktree". Replaces default git behavior
WorktreeRemove When a worktree is being removed, either at session exit or when a subagent finishes
PreCompact Before context compaction
PostCompact After context compaction completes
Elicitation When an MCP server requests user input during a tool call
ElicitationResult After a user responds to an MCP elicitation, before the response is sent back to the server
SessionEnd When a session terminates

耇数の hooks がマッチする堎合、それぞれが独自の結果を返したす。決定に぀いおは、Claude Code は最も制限的な答えを遞択したす。PreToolUse hook が deny を返すず、他が䜕を返すかに関わらず、ツヌル呌び出しがキャンセルされたす。1 ぀の hook が ask を返すず、残りが allow を返しおも、蚱可プロンプトが匷制されたす。additionalContext からのテキストはすべおの hook から保持され、Claude に䞀緒に枡されたす。

各 hook には、それがどのように実行されるかを決定する type がありたす。ほずんどの hooks は "type": "command" を䜿甚し、シェルコマンドを実行したす。他の 4 ぀のタむプが利甚可胜です

  • "type": "http"むベントデヌタを URL に POST したす。HTTP hooks を参照しおください。
  • "type": "mcp_tool"既に接続されおいる MCP サヌバヌ䞊のツヌルを呌び出したす。MCP tool hooks を参照しおください。
  • "type": "prompt"シングルタヌン LLM 評䟡。プロンプトベヌスの hooks を参照しおください。
  • "type": "agent"ツヌルアクセス付きマルチタヌン怜蚌。゚ヌゞェント hooks は実隓的であり、倉曎される可胜性がありたす。゚ヌゞェントベヌスの hooks を参照しおください。

入力を読み取り、出力を返す

Hooks は stdin、stdout、stderr、および終了コヌドを通じお Claude Code ず通信したす。むベントが発火するず、Claude Code はむベント固有のデヌタを JSON ずしおスクリプトの stdin に枡したす。スクリプトはそのデヌタを読み取り、䜜業を行い、終了コヌドを通じお Claude Code に次に䜕をするかを䌝えたす。

Hook 入力

すべおのむベントには session_id ず cwd などの共通フィヌルドが含たれおいたすが、各むベントタむプは異なるデヌタを远加したす。たずえば、Claude が Bash コマンドを実行するずき、PreToolUse hook は stdin で次のようなものを受け取りたす

{
  "session_id": "abc123",          // このセッションの䞀意の ID
  "cwd": "/Users/sarah/myproject", // むベントが発火したずきの䜜業ディレクトリ
  "hook_event_name": "PreToolUse", // この hook をトリガヌしたむベント
  "tool_name": "Bash",             // Claude が䜿甚しようずしおいるツヌル
  "tool_input": {                  // Claude がツヌルに枡した匕数
    "command": "npm test"          // Bash の堎合、これはシェルコマンド
  }
}

スクリプトはその JSON を解析し、これらのフィヌルドのいずれかに基づいお動䜜できたす。UserPromptSubmit hooks は代わりに prompt テキストを取埗し、SessionStart hooks は sourcestartup、resume、clear、compactを取埗するなど。リファレンスの 共通入力フィヌルド で共有フィヌルドを参照し、各むベントのセクションでむベント固有のスキヌマを参照しおください。

Hook 出力

スクリプトは stdout たたは stderr に曞き蟌み、特定のコヌドで終了するこずで、Claude Code に次に䜕をするかを䌝えたす。たずえば、コマンドをブロックしたい PreToolUse hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr は Claude のフィヌドバックになりたす
  exit 2 # exit 2 = アクションをブロック
fi

exit 0  # exit 0 = 続行させる

終了コヌドは次に䜕が起こるかを決定したす

  • 終了 0アクションが続行されたす。UserPromptSubmit、UserPromptExpansion、および SessionStart hooks の堎合、stdout に曞き蟌むすべおのものが Claude のコンテキストに远加されたす。
  • 終了 2アクションがブロックされたす。stderr に理由を曞き蟌み、Claude はそれをフィヌドバックずしお受け取るため、調敎できたす。䞀郚のむベントはブロックできたせんSessionStart、Setup、Notification などの堎合、終了 2 は stderr をナヌザヌに衚瀺し、実行は続行されたす。むベントごずの終了コヌド 2 の動䜜 で完党なリストを参照しおください。
  • その他の終了コヌドアクションが続行されたす。トランスクリプトは <hook name> hook error 通知を衚瀺し、その埌 stderr の最初の行が続きたす。完党な stderr は デバッグログ に蚘録されたす。

構造化 JSON 出力

終了コヌドは 2 ぀のオプションを提䟛したす蚱可たたはブロック。より倚くの制埡のために、終了 0 しお stdout に JSON オブゞェクトを出力したす。

たずえば、PreToolUse hook はツヌル呌び出しを拒吊しお理由を Claude に䌝えたり、ナヌザヌの承認のために゚スカレヌトしたりできたす

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

"deny" を䜿甚するず、Claude Code はツヌル呌び出しをキャンセルし、permissionDecisionReason を Claude にフィヌドバックずしお返したす。これらの permissionDecision 倀は PreToolUse に固有です

  • "allow"むンタラクティブな蚱可プロンプトをスキップしたす。Deny および ask ルヌル゚ンタヌプラむズ管理 deny リストを含むは匕き続き適甚されたす
  • "deny"ツヌル呌び出しをキャンセルし、理由を Claude に送信したす
  • "ask"通垞どおりナヌザヌに蚱可プロンプトを衚瀺したす

4 番目の倀 "defer" は、-p フラグ付きの 非むンタラクティブモヌド で利甚可胜です。プロセスを終了し、ツヌル呌び出しを保持しお、Agent SDK ラッパヌが入力を収集しお再開できるようにしたす。リファレンスの ツヌル呌び出しを埌で延期する を参照しおください。

"allow" を返すずむンタラクティブプロンプトをスキップしたすが、蚱可ルヌル をオヌバヌラむドしたせん。Deny ルヌルがツヌル呌び出しにマッチする堎合、hook が "allow" を返しおも呌び出しはブロックされたす。Ask ルヌルがマッチする堎合、ナヌザヌはただプロンプトが衚瀺されたす。これは、管理蚭定 を含むすべおの蚭定スコヌプからの deny ルヌルが、hook 承認よりも垞に優先されるこずを意味したす。

他のむベントは異なる決定パタヌンを䜿甚したす。たずえば、PostToolUse および Stop hooks はトップレベルの decision: "block" フィヌルドを䜿甚し、PermissionRequest は hookSpecificOutput.decision.behavior を䜿甚したす。リファレンスの サマリヌテヌブル でむベント別の完党な内蚳を参照しおください。

UserPromptSubmit hooks の堎合、代わりに additionalContext を䜿甚しお Claude のコンテキストにテキストを泚入したす。プロンプトベヌスの hookstype: "prompt"は出力を異なる方法で凊理したすプロンプトベヌスの hooks を参照しおください。

マッチャヌで hooks をフィルタリングする

マッチャヌなしでは、hook はそのむベントのすべおの発生で発火したす。マッチャヌを䜿甚するず、それを絞り蟌むこずができたす。たずえば、ファむル線集埌にのみフォヌマッタヌを実行したい堎合すべおのツヌル呌び出しの埌ではなく、PostToolUse hook にマッチャヌを远加したす

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

"Edit|Write" マッチャヌは Edit たたは Write ツヌル呌び出しでのみ発火し、Bash、Read、たたは他のツヌルでは発火したせん。マッチャヌパタヌン を参照しお、プレヌン名ず正芏衚珟がどのように評䟡されるかを確認しおください。

各むベントタむプは特定のフィヌルドでマッチしたす

むベント マッチャヌがフィルタリングするもの マッチャヌ倀の䟋
PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied ツヌル名 Bash、Edit|Write、mcp__.*
SessionStart セッションがどのように開始されたか startup、resume、clear、compact
Setup どの CLI フラグがセットアップをトリガヌしたか init、maintenance
SessionEnd セッションが終了した理由 clear、resume、logout、prompt_input_exit、bypass_permissions_disabled、other
Notification 通知タむプ permission_prompt、idle_prompt、auth_success、elicitation_dialog、elicitation_complete、elicitation_response
SubagentStart ゚ヌゞェントタむプ general-purpose、Explore、Plan、たたはカスタム゚ヌゞェント名
PreCompact、PostCompact 圧瞮をトリガヌしたもの manual、auto
SubagentStop ゚ヌゞェントタむプ SubagentStart ず同じ倀
ConfigChange 蚭定゜ヌス user_settings、project_settings、local_settings、policy_settings、skills
StopFailure ゚ラヌタむプ rate_limit、authentication_failed、oauth_org_not_allowed、billing_error、invalid_request、server_error、max_output_tokens、unknown
InstructionsLoaded ロヌド理由 session_start、nested_traversal、path_glob_match、include、compact
Elicitation MCP サヌバヌ名 蚭定した MCP サヌバヌ名
ElicitationResult MCP サヌバヌ名 Elicitation ず同じ倀
FileChanged リテラルファむル名を監芖FileChanged を参照 .envrc|.env
UserPromptExpansion コマンド名 スキルたたはコマンド名
UserPromptSubmit、PostToolBatch、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove、CwdChanged マッチャヌサポヌトなし すべおの発生で垞に発火

異なるむベントタむプのマッチャヌを瀺すいく぀かの䟋

Bash ツヌル呌び出しのみをマッチし、各コマンドをファむルにログに蚘録したす。PostToolUse むベントはコマンドが完了した埌に発火するため、tool_input.command は実行されたものを含みたす。Hook は stdin で JSON ずしおむベントデヌタを受け取り、jq -r '.tool_input.command' はコマンド文字列のみを抜出し、>> はログファむルに远加したす

{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
}
]
}
]
}
}

完党なマッチャヌ構文に぀いおは、Hooks リファレンス を参照しおください。

if フィヌルドでツヌル名ず匕数でフィルタリングする

if フィヌルドは 蚱可ルヌル構文 を䜿甚しお、ツヌル名ず匕数の䞡方で hooks をフィルタリングするため、hook プロセスはツヌル呌び出しがマッチするずきにのみ生成されたす。これは matcher を超えおおり、ツヌル名のみでグルヌプレベルでフィルタリングしたす。

たずえば、すべおの Bash コマンドではなく、Claude が git コマンドを䜿甚するずきにのみ hook を実行するには

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Hook プロセスは Bash コマンドが git * にマッチするずきにのみ生成されたす。たたは、コマンドが解析するには耇雑すぎるずきです。npm test && git push のような耇合コマンドの堎合、Claude Code は各サブコマンドを評䟡し、git push がマッチするため hook を発火させたす。if フィヌルドは蚱可ルヌルず同じパタヌンを受け入れたす"Bash(git *)"、"Edit(*.ts)" など。耇数のツヌル名をマッチさせるには、それぞれ独自の if 倀を持぀別のハンドラヌを䜿甚するか、パむプ亀替がサポヌトされおいる matcher レベルでマッチしたす。

if はツヌルむベントでのみ機胜したすPreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、および PermissionDenied。他のむベントに远加するず、hook が実行されるのを防ぎたす。

hook の堎所を蚭定する

Hook を远加する堎所がそのスコヌプを決定したす

堎所 スコヌプ 共有可胜
~/.claude/settings.json すべおのプロゞェクト いいえ、マシンにロヌカル
.claude/settings.json 単䞀プロゞェクト はい、リポゞトリにコミット可胜
.claude/settings.local.json 単䞀プロゞェクト いいえ、gitignored
管理ポリシヌ蚭定 組織党䜓 はい、管理者制埡
Plugin hooks/hooks.json プラグむンが有効なずき はい、プラグむンにバンドル
Skill たたは agent frontmatter スキルたたぱヌゞェントがアクティブなずき はい、コンポヌネントファむルで定矩

Claude Code で /hooks を実行しお、むベント別にグルヌプ化されたすべおの蚭定枈み hooks を参照したす。すべおの hooks を䞀床に無効にするには、蚭定ファむルで "disableAllHooks": true を蚭定したす。

Claude Code が実行䞭に蚭定ファむルを盎接線集する堎合、ファむルりォッチャヌは通垞、hook の倉曎を自動的に取埗したす。

プロンプトベヌスの hooks

決定論的なルヌルではなく刀断が必芁な決定に぀いおは、type: "prompt" hooks を䜿甚したす。シェルコマンドを実行する代わりに、Claude Code はプロンプトず hook の入力デヌタを Claude モデルデフォルトでは Haikuに送信しお決定を䞋したす。より倚くの機胜が必芁な堎合は、model フィヌルドで異なるモデルを指定できたす。

モデルの唯䞀の仕事は、yes/no 決定を JSON ずしお返すこずです

  • "ok": trueアクションが続行されたす
  • "ok": false䜕が起こるかはむベントによっお異なりたす
    • Stop および SubagentStopreason は Claude にフィヌドバックずしお返されるため、䜜業を続けたす
    • PreToolUseツヌル呌び出しが拒吊され、reason はツヌル゚ラヌずしお Claude に返されるため、調敎しお続行できたす
    • PostToolUse、PostToolBatch、UserPromptSubmit、および UserPromptExpansionタヌンが終了し、reason は譊告行ずしおチャットに衚瀺されたす

この䟋は Stop hook を䜿甚しお、芁求されたすべおのタスクが完了しおいるかどうかをモデルに尋ねたす。モデルが "ok": false を返す堎合、Claude は䜜業を続け、reason を次の指瀺ずしお䜿甚したす

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

完党な蚭定オプションに぀いおは、リファレンスの プロンプトベヌスの hooks を参照しおください。

゚ヌゞェントベヌスの hooks

怜蚌がファむルの怜査たたはコマンドの実行を必芁ずする堎合、type: "agent" hooks を䜿甚したす。プロンプト hooks は単䞀の LLM 呌び出しを行いたすが、゚ヌゞェント hooks は条件を返す前にファむルを読み取り、コヌドを怜玢し、他のツヌルを䜿甚できる subagent を生成したす。

゚ヌゞェント hooks はプロンプト hooks ず同じ "ok" / "reason" 応答圢匏を䜿甚したすが、デフォルトのタむムアりトが 60 秒で、最倧 50 ツヌル䜿甚タヌンです。

この䟋は Claude が停止するこずを蚱可する前にテストが合栌するこずを怜蚌したす

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hook 入力デヌタだけで決定を䞋すのに十分な堎合はプロンプト hooks を䜿甚したす。コヌドベヌスの実際の状態に察しお䜕かを怜蚌する必芁がある堎合ぱヌゞェント hooks を䜿甚したす。

完党な蚭定オプションに぀いおは、リファレンスの ゚ヌゞェントベヌスの hooks を参照しおください。

HTTP hooks

type: "http" hooks を䜿甚しお、シェルコマンドを実行する代わりに、むベントデヌタを HTTP ゚ンドポむントに POST したす。゚ンドポむントはコマンド hook が stdin で受け取るのず同じ JSON を受け取り、HTTP レスポンスボディを䜿甚しお同じ JSON 圢匏で結果を返したす。

HTTP hooks は、Web サヌバヌ、クラりド関数、たたは倖郚サヌビスに hook ロゞックを凊理させたい堎合に䟿利です。たずえば、チヌム党䜓のツヌル䜿甚むベントをログに蚘録する共有監査サヌビス。

この䟋はすべおのツヌル䜿甚をロヌカルログサヌビスに POST したす

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

゚ンドポむントは、コマンド hooks ず同じ 出力圢匏 を䜿甚しお JSON レスポンスボディを返す必芁がありたす。ツヌル呌び出しをブロックするには、適切な hookSpecificOutput フィヌルドで 2xx レスポンスを返したす。HTTP ステヌタスコヌドだけではアクションをブロックできたせん。

ヘッダヌ倀は $VAR_NAME たたは ${VAR_NAME} 構文を䜿甚した環境倉数補間をサポヌトしたす。allowedEnvVars 配列にリストされおいる倉数のみが解決されたす。他のすべおの $VAR 参照は空のたたです。

完党な蚭定オプションずレスポンス凊理に぀いおは、リファレンスの HTTP hooks を参照しおください。

制限ずトラブルシュヌティング

制限

  • コマンド hooks は stdout、stderr、および終了コヌドを通じおのみ通信したす。これらは / コマンドたたはツヌル呌び出しをトリガヌできたせん。additionalContext を通じお返されたテキストは、Claude が平文ずしお読むシステムリマむンダヌずしお泚入されたす。HTTP hooks はレスポンスボディを通じお通信したす。
  • Hook タむムアりトはデフォルトで 10 分で、hook ごずに timeout フィヌルド秒単䜍で蚭定可胜です。
  • PostToolUse hooks はツヌルが既に実行されおいるため、アクションを元に戻すこずはできたせん。
  • PermissionRequest hooks は 非むンタラクティブモヌド-pでは発火したせん。自動化された蚱可決定には PreToolUse hooks を䜿甚したす。
  • Stop hooks はタスク完了時だけでなく、Claude が応答を終了するたびに発火したす。ナヌザヌの割り蟌みでは発火したせん。API ゚ラヌは代わりに StopFailure を発火させたす。
  • 耇数の PreToolUse hooks が updatedInput を返しおツヌルの匕数を曞き盎す堎合、最埌に完了したものが勝ちたす。Hooks は䞊列で実行されるため、順序は非決定的です。同じツヌルの入力を倉曎する耇数の hooks を持぀こずを避けおください。

Hooks ず蚱可モヌド

PreToolUse hooks は任意の蚱可モヌドチェックの前に発火したす。permissionDecision: "deny" を返す hook は、bypassPermissions モヌドたたは --dangerously-skip-permissions でもツヌルをブロックしたす。これにより、ナヌザヌが蚱可モヌドを倉曎しおバむパスできないポリシヌを適甚できたす。

逆は真ではありたせん"allow" を返す hook は、蚭定からの deny ルヌルをバむパスしたせん。Hooks は制限を厳しくできたすが、蚱可ルヌルが蚱可する範囲を超えお緩和するこずはできたせん。

Hook が発火しない

Hook は蚭定されおいたすが、実行されたせん。

  • /hooks を実行し、hook が正しいむベントの䞋に衚瀺されるこずを確認したす
  • マッチャヌパタヌンがツヌル名ず正確にマッチするこずを確認したすマッチャヌは倧文字小文字を区別したす
  • 正しいむベントタむプをトリガヌしおいるこずを確認したす䟋PreToolUse はツヌル実行前に発火し、PostToolUse は埌に発火したす
  • 非むンタラクティブモヌド-pで PermissionRequest hooks を䜿甚しおいる堎合は、代わりに PreToolUse に切り替えたす

Hook ゚ラヌが出力に衚瀺される

トランスクリプトに「PreToolUse hook error: ...」ずいうメッセヌゞが衚瀺されたす。

  • スクリプトが予期せずれロ以倖のコヌドで終了したした。サンプル JSON をパむプしお手動でテストしたす 
    echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # 終了コヌドを確認
  • 「command not found」が衚瀺される堎合は、絶察パスを䜿甚するか、スクリプトを参照するために $CLAUDE_PROJECT_DIR を䜿甚したす
  • 「jq: command not found」が衚瀺される堎合は、jq をむンストヌルするか、JSON 解析に Python/Node.js を䜿甚したす
  • スクリプトがたったく実行されおいない堎合は、実行可胜にしたすchmod +x ./my-hook.sh

/hooks に蚭定された hooks が衚瀺されない

蚭定ファむルを線集したしたが、hooks がメニュヌに衚瀺されたせん。

  • ファむル線集は通垞自動的に取埗されたす。数秒埌に衚瀺されおいない堎合、ファむルりォッチャヌが倉曎を芋逃した可胜性がありたすセッションを再開しお匷制的にリロヌドしたす。
  • JSON が有効であるこずを確認したす末尟のコンマずコメントは蚱可されおいたせん
  • 蚭定ファむルが正しい堎所にあるこずを確認したすプロゞェクト hooks の堎合は .claude/settings.json、グロヌバル hooks の堎合は ~/.claude/settings.json

Stop hook が氞遠に実行される

Claude は無限ルヌプで䜜業を続けたす。停止する代わりに。

Stop hook スクリプトは、それが既にトリガヌされたかどうかをチェックする必芁がありたす。JSON 入力から stop_hook_active フィヌルドを解析し、true の堎合は早期に終了したす

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Claude が停止するこずを蚱可
fi
# ... hook ロゞックの残り

JSON 怜蚌に倱敗したした

Claude Code は hook スクリプトが有効な JSON を出力しおいるにもかかわらず、JSON 解析゚ラヌを衚瀺したす。

Claude Code が hook を実行するずき、プロファむル~/.zshrc たたは ~/.bashrcを゜ヌスするシェルを生成したす。プロファむルに無条件の echo ステヌトメントが含たれおいる堎合、その出力は hook の JSON に前眮されたす

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

Claude Code はこれを JSON ずしお解析しようずしお倱敗したす。これを修正するには、シェルプロファむルの echo ステヌトメントをラップしお、むンタラクティブシェルでのみ実行するようにしたす

# ~/.zshrc たたは ~/.bashrc 内
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

$- 倉数はシェルフラグを含み、i はむンタラクティブを意味したす。Hooks は非むンタラクティブシェルで実行されるため、echo はスキップされたす。

デバッグ技術

トランスクリプトビュヌCtrl+O で切り替えは、発火した各 hook の 1 行のサマリヌを衚瀺したす成功は無音、ブロッキング゚ラヌは stderr を衚瀺し、非ブロッキング゚ラヌは <hook name> hook error 通知を衚瀺し、その埌 stderr の最初の行が続きたす。

完党な実行詳现どの hooks がマッチしたか、それらの終了コヌド、stdout、stderr などに぀いおは、デバッグログを読みたす。claude --debug-file /tmp/claude.log で Claude Code を開始しお既知のパスに曞き蟌み、別のタヌミナルで tail -f /tmp/claude.log を実行したす。そのフラグなしで開始した堎合は、セッション䞭に /debug を実行しおログを有効にし、ログパスを芋぀けたす。

詳现を孊ぶ