hook-authoring

使用しない場合

• 既存のフックを監査する場合（abstract:hooks-evalを使用）
• フックを配置する場所を選ぶ場合（abstract:hook-scope-guideを使用）
• フックではなくスキルを作成する場合（abstract:skill-authoringを使用）

フック作成ガイド

概要

フックはイベントインターセプターです。エージェントのライフサイクルにおける特定のタイミングでカスタムロジックを実行し、Claude Code と Claude Agent SDK の動作を拡張できます。ツールの使用前の検証、アクション後のログ記録、コンテキストの注入、ワークフローの自動化、セキュリティの適用が可能です。

このスキルでは、宣言的な JSON（Claude Code）とプログラムによる Python（Claude Agent SDK）の両方のユースケースに対応した、効果的で安全かつパフォーマンスに優れたフックの作成方法を説明します。

主な機能

• PreToolUse：実行前にツールの入力を検証、フィルタリング、または変換します。コンテキストの注入も可能です（2.1.9+）
• PostToolUse：実行後にツールの出力を記録、分析、または変更します
• UserPromptSubmit：処理前にコンテキストを注入したり、ユーザーメッセージをフィルタリングしたりします
• Stop/SubagentStop：クリーンアップ、最終報告、または結果の集約を行います
• TeammateIdle/TaskCompleted：マルチエージェントの連携とオーケストレーションを行います（2.1.33+）
• PreCompact：コンテキストウィンドウを圧縮する前に状態を保持します

2.1.9 の新機能：PreToolUse フックは、ツールの実行前に情報を注入するadditionalContextを返せるようになりました。これにより、キャッシュのヒント、セキュリティ警告、関連するコンテキストの注入などのパターンを実現できます。

クイックスタート

初めてのフック（JSON - Claude Code）

.claude/settings.jsonにシンプルなログ記録フックを作成します。

{
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo \"$(date): Executed $(jq -r '.tool_name')\" >> ~/.claude/audit.log"
      }]
    }
  ]
}

注意：オブジェクトマッチャー（{"toolName": "Bash"}）ではなく、文字列マッチャー（"Bash"）を使用してください。

検証： --helpフラグを付けてコマンドを実行し、利用可能であることを確認します。

このフックは、すべての Bash コマンドの実行をタイムスタンプ付きで記録します。

初めてのフック（Python - Claude Agent SDK）

SDK を使用して検証フックを作成します。

from claude_agent_sdk import AgentHooks


class ValidationHooks(AgentHooks):
    async def on_pre_tool_use(self, tool_name: str, tool_input: dict) -> dict | None:
        """Validate tool inputs before execution."""
        if tool_name == "Bash":
            command = tool_input.get("command", "")
            if "rm -rf /" in command:
                raise ValueError("Dangerous command blocked by hook")

        # Return None to proceed unchanged, or modified dict to transform
        return None

検証： --helpフラグを付けてコマンドを実行し、利用可能であることを確認します。

フックのイベントタイプ

サポートされているすべてのフックイベントのクイックリファレンス：

イベント	トリガーされるタイミング	パラメーター	一般的な用途
PreToolUse	ツールの実行前	tool_name、tool_input	検証、フィルタリング、入力の変換
PostToolUse	ツールの実行後	tool_name、tool_input、tool_output	ログ記録、メトリクス、出力の変換
UserPromptSubmit	ユーザーがメッセージを送信したとき	message	コンテキストの注入、コンテンツのフィルタリング
PermissionRequest	権限ダイアログが表示されたとき	tool_name、tool_input	カスタムロジックによる自動承認／拒否
Notification	Claude Code が通知を送信したとき	message	カスタム通知の処理
Stop	エージェントが完了したとき	reason、result	最終クリーンアップ、要約レポート
SubagentStop	サブエージェントが完了したとき	subagent_id、result	結果の処理、集約
TeammateIdle	チームメイトのエージェントがアイドル状態になったとき	agent_id、session_id	作業の割り当て、負荷分散（2.1.33+）
TaskCompleted	タスクの実行が完了したとき	task_id、result	連携、連鎖、報告（2.1.33+）
PreCompact	コンテキストを圧縮する前	context_size	状態の保持、チェックポイントの作成
SessionStart	セッションが開始／再開したとき	session_id、source、agent_type	初期化、コンテキストの読み込み
SessionEnd	セッションが終了したとき	session_id	クリーンアップ、最終ログの記録
WorktreeCreate	エージェントのワークツリーが作成されたとき	worktree_path、session_id	カスタム VCS の設定、.venv のシンボリックリンク作成、キャッシュの事前生成（2.1.50+）
WorktreeRemove	エージェントのワークツリーが削除されたとき	worktree_path、session_id	一時ファイルのクリーンアップ、ワークツリー専用リソースの終了処理（2.1.50+）

SessionStart 入力スキーマ（Claude Code 2.1.2+）

SessionStart フックは、次のフィールドを含む JSON 入力を stdin 経由で受け取ります。

{
  "session_id": "abc123",
  "source": "startup",
  "agent_type": "my-agent"
}

フィールド：source は "startup"、"resume"、"clear"、"compact" のいずれかです。--agent フラグを使用すると、agent_type が設定されます。

agent_type フィールド：Claude Code を --agent my-agent で起動すると、このフィールドにエージェント名が設定され、エージェント固有の初期化が可能になります。

# Python example: Agent-aware SessionStart hook
input_data = json.loads(sys.stdin.read())
agent_type = input_data.get("agent_type", "")

if agent_type in ["code-reviewer", "quick-query"]:
    # Skip heavy context injection for lightweight agents
    print(json.dumps({"hookSpecificOutput": {"additionalContext": "Minimal context"}}))
else:
    # Full initialization for implementation agents
    print(json.dumps({"hookSpecificOutput": {"additionalContext": full_context}}))

# Bash example: Agent-aware SessionStart hook
HOOK_INPUT=$(cat)
AGENT_TYPE=$(echo "$HOOK_INPUT" | jq -r '.agent_type // empty')

case "$AGENT_TYPE" in
    code-reviewer|quick-query)
        echo '{"hookSpecificOutput": {"additionalContext": "Minimal context"}}'
        ;;
    *)
        echo '{"hookSpecificOutput": {"additionalContext": "Full context"}}'
        ;;
esac

Frontmatter のフック（Claude Code 2.1.0+）

2.1.0 の新機能： スキル、コマンド、エージェントの frontmatter にフックを直接定義できます。これらのフックは、コンポーネントのライフサイクルにスコープされます。

スキル／コマンド／エージェントの frontmatter フック

---
name: validated-skill
description: Skill with lifecycle hooks
hooks:
  PreToolUse:
    - matcher: "Bash"
      command: "./validate-command.sh"
      once: true  # NEW: Run only once per session
    - matcher: "Write|Edit"
      command: "./pre-edit-check.sh"
  PostToolUse:
    - matcher: "Write|Edit"
      command: "./format-on-save.sh"
  Stop:
    - command: "./cleanup-and-report.sh"
---

once: true の設定

2.1.0 の新機能： once: true を使用すると、セッションごとにフックを一度だけ実行できます。次の用途に適しています。

• 一度限りのセットアップ／初期化
• 繰り返し実行すべきでないリソースの割り当て
• セッション単位の設定

hooks:
  PreToolUse:
    - matcher: "Bash"
      command: "./setup-environment.sh"
      once: true  # Runs only on first Bash call
  SessionStart:
    - command: "./initialize-session.sh"
      once: true  # Runs only once at session start

Frontmatter フックと Settings フックの比較

項目	Frontmatter フック	Settings フック
スコープ	コンポーネントのライフサイクル	グローバル／プロジェクト
場所	スキル／エージェント／コマンド内	settings.json
永続性	コンポーネントの実行中のみ有効	常に有効
用途	コンポーネント固有の検証	横断的な関心事

PreToolUse の updatedInput を更新（2.1.0 の修正）

PreToolUse フックは、ask 権限の判断を返す際に updatedInput も返せるようになりました。これにより、ユーザーの同意を求めながら、フックをミドルウェアとして動作させることができます。

{
  "decision": "ask",
  "updatedInput": {
    "command": "modified-command --safe-flag"
  }
}

Claude Code と SDK の比較

JSON フック（Claude Code）

.claude/settings.json、プロジェクトの .claude/settings.json、またはプラグインの hooks/hooks.json に宣言型設定を記述します。

{
  "PreToolUse": [
    {
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "echo 'WARNING: Editing production file' >&2"
      }]
    }
  ]
}

重要： オブジェクト形式のマッチャーではなく、文字列マッチャー（正規表現パターン）を使用してください。{"toolName": "Edit"} のオブジェクト形式は非推奨です。

マッチャーパターン：

• "Edit" - 単一のツールに一致
• "Read|Write|Edit" - 複数のツールに一致（正規表現の OR）
• ".*" - すべてのツールに一致

確認： コマンドに --help フラグを付けて実行し、利用可能かどうかを確認してください。

利点： シンプルで、コードが不要であり、バージョン管理も容易です
欠点： ロジック機能が限られ、シェルコマンドのみ使用できます

HTTP フック（Claude Code 2.1.63+）

2.1.63 の新機能： フックはシェルコマンドを実行する代わりに、JSON を URL に POST し、JSON レスポンスを受け取れるようになりました。"type": "http" と "url" フィールドを使用します。

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "http",
        "url": "https://my-service.example.com/hooks/validate-bash"
      }]
    }
  ]
}

フックは標準のフック入力を JSON として POST し、標準のフックレスポンス JSON 本文を想定します。

コマンドフックより HTTP フックを使用する場面：

• シェル実行が制限されているエンタープライズ環境
• Web サービスを介してチーム間で共有する一元化されたフックロジック
• ローカルスクリプトにアクセスできないサンドボックス環境やコンテナ環境
• 外部の検証／ロギングサービスとの統合

利点： ローカルスクリプトが不要で、ロジックを一元化でき、サンドボックス環境で動作します
欠点： ネットワーク遅延が発生し、HTTP サービスの稼働が必要で、外部依存があります

Python SDK フック

AgentHooks 基底クラスを使用したプログラムによるコールバック：

from claude_agent_sdk import AgentHooks


class MyHooks(AgentHooks):
    async def on_pre_tool_use(self, tool_name: str, tool_input: dict) -> dict | None:
        # Complex validation logic
        if self._is_dangerous(tool_input):
            raise ValueError("Operation blocked")
        return None  # or return modified input

確認： コマンドに --help フラグを付けて実行し、利用可能かどうかを確認してください。

利点： Python の機能をすべて活用でき、複雑なロジックや状態管理に対応します
欠点： Python が必要で、セットアップがより複雑です

Bash 権限のマッチングに関する注意事項

環境変数のラッパー（2.1.38+）

権限ルールが、環境変数の代入を前置したコマンドに正しく一致するようになりました。2.1.38 より前は、NODE_ENV=production npm test は Bash(npm *) のルールに一致しませんでした。

# These now all match `Bash(npm *)`:
npm test
NODE_ENV=production npm test
FORCE_COLOR=1 CI=true npm test

Bash コマンドを調べる PreToolUse フックを作成する場合、権限システムはマッチング時に環境変数のプレフィックスを取り除きますが、フックにはプレフィックスを含むコマンド文字列全体が渡される点に注意してください。

Heredoc 区切り文字のセキュリティ（2.1.38+）

Claude Code は、コマンドの紛れ込みを防ぐため、heredoc の区切り文字を検証するようになりました。推奨パターンの <<'EOF'（シングルクォート付き）は、引き続き最も安全な方法です。変数展開を防ぐため、heredoc パターンでは必ずシングルクォート付きの区切り文字を使用してください。

セキュリティの基本事項

重要なセキュリティルール

1. 入力の検証：処理する前に、必ずツールの入力を検証してください
2. シークレットをログに記録しない：API キー、トークン、パスワード、認証情報をログに記録しないでください
3. サンドボックスを意識する：サンドボックスの境界を尊重し、逸脱しないでください。注：サンドボックスモードでは、.claude/skills/ は読み取り専用です（2.1.38+）
4. フェイルセーフのデフォルト：エージェントをブロックする代わりに、エラー時は None を返してください
5. レート制限：悪意のあるコードやバグのあるコードによるフックの悪用を防いでください
6. インジェクションの防止：ログインジェクションを防ぐため、ログに記録するすべての内容をサニタイズしてください

例：安全なログ記録フック

import re
from claude_agent_sdk import AgentHooks


class SecureLoggingHooks(AgentHooks):
    # Patterns that might contain secrets
    SECRET_PATTERNS = [
        r"api[_-]?key",
        r"password",
        r"token",
        r"secret",
        r"credential",
        r"auth",
    ]

    def _sanitize_output(self, text: str) -> str:
        """Remove potential secrets from log output."""
        for pattern in self.SECRET_PATTERNS:
            text = re.sub(
                rf'({pattern}["\s:=]+)([^\s,}}]+)',
                r"\1***REDACTED***",
                text,
                flags=re.IGNORECASE,
            )
        return text

    async def on_post_tool_use(
        self, tool_name: str, tool_input: dict, tool_output: str
    ) -> str | None:
        """Log tool use with sanitization."""
        safe_output = self._sanitize_output(tool_output)
        # Log safe_output...
        return None  # Don't modify output

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

詳細なセキュリティガイダンスについては、modules/testing-hooks.md を参照してください。

パフォーマンスガイドライン

パフォーマンスのベストプラクティス

1. ノンブロッキング：async／await を適切に使用し、イベントループをブロックしないでください
2. タイムアウト処理：フックのタイムアウトは 10 分です（2.1.3 で 60s から延長）。ほとんどのフックは 30s 未満を目指してください。延長時間は、CI/CD 連携、複雑な検証、外部 API 呼び出しにのみ使用してください
3. 効率的なログ記録：書き込みをまとめ、非同期 I/O を使用してください
4. メモリ管理：上限のない状態を蓄積しないでください
5. 高速な失敗：検証を素早く行い、早期にリターンし、コストの高い処理を避けてください

例：効率的なフック

import asyncio
from claude_agent_sdk import AgentHooks


class EfficientHooks(AgentHooks):
    def __init__(self):
        self._log_queue = asyncio.Queue()
        self._log_task = None

    async def on_pre_tool_use(self, tool_name: str, tool_input: dict) -> dict | None:
        # Quick validation only
        if not self._is_valid_input(tool_input):
            raise ValueError("Invalid input")
        return None

    async def on_post_tool_use(
        self, tool_name: str, tool_input: dict, tool_output: str
    ) -> str | None:
        # Queue log entry without blocking
        await self._log_queue.put({"tool": tool_name, "timestamp": time.time()})
        return None

    def _is_valid_input(self, tool_input: dict) -> bool:
        """Fast validation check."""
        # Simple checks only, < 10ms
        return len(str(tool_input)) < 1_000_000

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

詳細な最適化手法については、modules/performance-guidelines.md を参照してください。

スコープの選択

対象ユーザーと目的に応じて、フックを配置する場所を選択してください。

重要：自動読み込みの動作

hooks/hooks.json は、プラグインが有効になると自動的に読み込まれます。 plugin.json に "hooks": "./hooks/hooks.json" を追加しないでください。重複読み込みエラーの原因になります。 標準の場所にあるもの以外のフックファイルを追加する場合に限り、hooks フィールドを使用してください。

判断の枠組み

**Verification:** Run the command with `--help` flag to verify availability.
Is this hook part of a plugin's core functionality?
├─ YES → Plugin hooks (hooks/hooks.json in plugin)
└─ NO ↓

Should all team members on this project have this hook?
├─ YES → Project hooks (.claude/settings.json)
└─ NO ↓

Should this hook apply to all my Claude sessions?
├─ YES → Global hooks (~/.claude/settings.json)
└─ NO → Reconsider if you need a hook at all

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

スコープの比較

スコープ	場所	対象ユーザー	コミットするか	使用例
プラグイン	hooks/hooks.json	プラグインのユーザー	はい（プラグインとともに）	YAML プラグインでの YAML 検証
プロジェクト	.claude/settings.json	チームメンバー	はい（リポジトリ内）	本番環境の設定編集をブロック
グローバル	~/.claude/settings.json	自分のみ	いいえ	個人用の監査ログ記録

詳細なスコープ選択のガイダンスについては、modules/scope-selection.md を参照してください。

一般的なパターン

検証フック

実行前に危険な操作をブロックします：

async def on_pre_tool_use(self, tool_name: str, tool_input: dict) -> dict | None:
    if tool_name == "Bash":
        command = tool_input.get("command", "")

        # Block dangerous patterns
        if any(pattern in command for pattern in ["rm -rf /", ":(){ :|:& };:"]):
            raise ValueError(f"Dangerous command blocked: {command}")

        # Block production access
        if "production" in command and not self._has_approval():
            raise ValueError("Production access requires approval")

    return None

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

ログ記録フック

すべてのツール操作を監査します：

async def on_post_tool_use(
    self, tool_name: str, tool_input: dict, tool_output: str
) -> str | None:
    await self._log_entry(
        {
            "timestamp": datetime.now().isoformat(),
            "tool": tool_name,
            "input_size": len(str(tool_input)),
            "output_size": len(tool_output),
            "success": True,
        }
    )
    return None

確認： --help フラグを付けてコマンドを実行し、利用可能であることを確認してください。

コンテキスト注入フック

ユーザーのプロンプトの前に、関連するコンテキストを追加します：

async def on_user_prompt_submit(self, message: str) -> str | None:
    # Inject project-specific context
    context = await self._load_project_context()
    enhanced_message = f"{context}\n\n{message}"
    return enhanced_message

PreToolUse コンテキスト注入（Claude Code 2.1.9+）

additionalContext を使用して、ツールの実行前にコンテキストを注入します：

#!/usr/bin/env python3
"""PreToolUse hook that injects context before WebFetch."""

import json
import sys


def main():
    payload = json.load(sys.stdin)
    tool_name = payload.get("tool_name", "")

    if tool_name == "WebFetch":
        url = payload.get("tool_input", {}).get("url", "")
        # Check cache or knowledge base
        cached = lookup_knowledge_base(url)
        if cached:
            print(
                json.dumps(
                    {
                        "hookSpecificOutput": {
                            "hookEventName": "PreToolUse",
                            "additionalContext": f"Relevant cached info: {cached}",
                        }
                    }
                )
            )
    sys.exit(0)


if __name__ == "__main__":
    main()

このパターンは、ウェブリクエスト前のキャッシュヒント、リスクのある操作前のセキュリティ警告、ファイル操作前の関連するプロジェクトコンテキストの注入に役立ちます。

フックのテスト

単体テスト

import pytest
from my_hooks import ValidationHooks


@pytest.mark.asyncio
async def test_dangerous_command_blocked():
    hooks = ValidationHooks()

    with pytest.raises(ValueError, match="Dangerous command"):
        await hooks.on_pre_tool_use("Bash", {"command": "rm -rf /"})


@pytest.mark.asyncio
async def test_safe_command_allowed():
    hooks = ValidationHooks()
    result = await hooks.on_pre_tool_use("Bash", {"command": "ls -la"})
    assert result is None  # Allows execution

確認： pytest -v from を実行して確認してください。

詳細なテスト戦略については、modules/testing-hooks.md を参照してください。

モジュールリファレンス

特定のトピックについて詳しくは、以下を参照してください。

• フックの種類：modules/hook-types.md - イベントのシグネチャとパラメーターの詳細
• SDK コールバック：modules/sdk-callbacks.md - Python SDK の実装パターン
• セキュリティパターン：modules/testing-hooks.md - 詳細なセキュリティガイダンス
• パフォーマンスガイドライン：modules/performance-guidelines.md - 最適化の手法
• スコープの選択：modules/scope-selection.md - プラグイン／プロジェクト／グローバルの選択
• フックのテスト：modules/testing-hooks.md - テスト戦略とフィクスチャ
• 可観測性に関する警告：modules/observability-warnings.md - バイナリ判定可能なドリフトフック用のコピーして使える解決パターン

ツール

• hook_validator.py：フックの構造と構文を検証します（ plugins/abstract/scripts/hook_validator.py）

関連スキル

• hook-scope-guide：フックの配置を決めるためのフレームワーク（既存）
• modular-skills：スキルアーキテクチャの設計パターン
• skills-eval：品質評価と改善のフレームワーク

次のステップ

1. 複雑さの要件に応じて、フックの種類（JSON または SDK）を選択します
2. 適切なスコープ（プラグイン／プロジェクト／グローバル）を選択します
3. セキュリティとパフォーマンスのベストプラクティスに従って実装します
4. 単体テストと統合テストで十分にテストします
5. デプロイ前に hook_validator.py を使って検証します

環境変数（Claude Code 2.1.2+）

FORCE_AUTOUPDATE_PLUGINS

Claude Code のメインの自動アップデーターが無効になっていても、プラグインの自動アップデートを強制します。

使用例：

• 最新のプラグインバージョンが必要な CI/CD パイプライン
• プラグインのアップデートをテストする開発環境
• エンタープライズ環境での管理されたアップデート展開

# Enable forced plugin updates
export FORCE_AUTOUPDATE_PLUGINS=1
claude

# Or inline
FORCE_AUTOUPDATE_PLUGINS=1 claude --agent my-agent

注：これはプラグインのアップデートにのみ影響し、Claude Code コアのアップデートには影響しません。

参考資料

• Claude Code フックのドキュメント
• Claude Agent SDK のドキュメント
• 設定

フックの終了コード

フックは終了コードを介して、Claude Code に判断結果を伝えます。

終了コード	意味	stdout	stderr
0	成功／許可	システムコンテキストとして Claude に表示されます	無視されます
2	ブロック／拒否	無視されます	説明としてユーザーに表示されます（2.1.39+ で修正）
その他	エラー	無視されます	エラーメッセージとしてユーザーに表示されます

終了コード 2 によるブロック（2.1.39+）

終了コード 2 を使用すると、アクションをブロックしてユーザーにメッセージを表示できます。

#!/bin/bash
# Example: Block force pushes with user-facing message
command=$(echo "$1" | jq -r '.tool_input.command // empty')
if echo "$command" | grep -q 'push.*--force'; then
  echo "Force push blocked: use --force-with-lease instead" >&2
  exit 2
fi
exit 0

重要：Claude Code 2.1.39 より前のバージョンでは、終了コード 2 の stderr は通知されずに破棄されていました（#10964）。ユーザーにはカスタムメッセージの代わりに、一般的な「フックエラー」が表示されていました。この問題は修正され、stderr が正しくユーザーに表示されるようになりました。

プラグインフック：2.1.39 より前のバージョンでは、プラグインがインストールしたフックには別のコードパスがあり、終了コード 2 の stderr が表示されない問題も発生していました（#10412）。現在は、プラグインフックとプロジェクトフックの両方が正しく動作します。

トラブルシューティング

よくある問題

フックが実行されない フックのパターンがイベントに一致しているか確認してください。フックログにエラーがないか確認してください。

構文エラー デプロイ前に JSON／Python の構文を検証してください。

アクセスが拒否される フックファイルのアクセス許可と所有者を確認してください。

フックのブロックメッセージが表示されない（2.1.39 より前） 終了コード 2 を使ってユーザー向けメッセージとともにブロックしようとしても、メッセージが表示されない場合は、Claude Code 2.1.39 以降にアップグレードしてください。旧バージョンでは、回避策として終了コード 0 と stdout を使用してください。

終了条件

• 作成したフックファイルが有効なスコープの場所（hooks/hooks.json、 .claude/settings.json、または ~/.claude/settings.json）にあり、JSON または Python の構文が正しいこと。
• フックが対象イベントで実行されること：一致するツール呼び出しをテストで実行すると、フックコマンドまたはコールバックがエラーなく起動すること。
• フックに秘密情報のログ出力が含まれていないこと：ログ出力先のパスに、api[_-]?key、password、 token、secret、credential に一致するフィールド名が含まれていないこと。
• ブロッキングフックは終了コード 2 で終了し、ユーザー向けの説明を標準出力ではなく標準エラー出力に書き込むこと。
• abstract:validate-hook が利用可能な場合、作成したフックファイルに対して終了コード 0 で終了すること。