hooks-eval

使用しないケース

• 新しいフックを作成する場合（abstract:hook-authoring を使用）
• スキルを評価する場合（abstract:skills-eval を使用）
• .claude/rules/ のルールを評価する場合（abstract:rules-eval を使用）

フック評価フレームワーク

概要

このスキルでは、すべてのスコープ（プラグイン、プロジェクト、グローバル）と、JSON ベースおよびプログラムによる（Python SDK）フックの両方を対象に、Claude Code のフックを評価、監査、実装するための詳細なフレームワークを提供します。

主な機能

• セキュリティ分析：脆弱性スキャン、危険なパターンの検出、インジェクションの防止
• パフォーマンス分析：実行時間のベンチマーク、リソース使用量、最適化
• コンプライアンスチェック：構造の検証、ドキュメント要件、ベストプラクティス
• SDK 統合：Python SDK のフックタイプ、コールバック、マッチャー、パターン

主なコンポーネント

コンポーネント	目的
フックタイプのリファレンス	SDK のフックイベントタイプとシグネチャの完全な一覧
評価基準	スコアリングシステムと品質ゲート
セキュリティパターン	一般的な脆弱性と緩和策
パフォーマンスベンチマーク	しきい値と最適化の指針

クイックリファレンス

フックイベントタイプ

HookEvent = Literal[
    "PreToolUse",  # Before tool execution
    "PostToolUse",  # After tool execution
    "UserPromptSubmit",  # When user submits prompt
    "Stop",  # When stopping execution
    "SubagentStop",  # When a subagent stops
    "TeammateIdle",  # When teammate agent becomes idle (2.1.33+)
    "TaskCompleted",  # When a task finishes execution (2.1.33+)
    "PreCompact",  # Before message compaction
]

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

注： Python SDK はセットアップ上の制約により、SessionStart、SessionEnd、Notification フックをサポートしていません。ただし、プラグインでは、シェルコマンド（例：leyline の detect-git-platform.sh）を使用して、hooks.json で SessionStart フックを定義できます。

プラグインレベルの hooks.json

プラグインでは、plugin.json に "hooks": "./hooks/hooks.json" を指定してフックを宣言できます。評価ツールは以下を検証します。

• 参照先の hooks.json が存在し、有効な JSON であること
• フック内で参照されているシェルコマンドが存在し、実行可能であること
• フックのマッチャーが有効なイベントタイプを使用していること

フックコールバックのシグネチャ

async def my_hook(
    input_data: dict[str, Any],  # Hook-specific input
    tool_use_id: str | None,  # Tool ID (for tool hooks)
    context: HookContext,  # Additional context
) -> dict[str, Any]:  # Return decision/messages
    ...

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

戻り値

return {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",  # Match hook type
        "permissionDecision": "deny",  # Optional: block action
        "permissionDecisionReason": "...",  # Reason for denial
        "additionalContext": "...",  # Optional: context added
    }
}

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

品質スコア（100 点）

カテゴリ	点数	対象
セキュリティ	30	脆弱性、インジェクション、検証
パフォーマンス	25	実行時間、メモリ、I/O
コンプライアンス	20	構造、ドキュメント、エラー処理
信頼性	15	タイムアウト、冪等性、縮退
保守性	10	コード構造、モジュール性

詳細リソース

• SDK フックタイプ：Python SDK の型定義、パターン、例については modules/sdk-hook-types.md を参照してください
• 評価基準：詳細なスコアリング基準と品質ゲートについては modules/evaluation-criteria.md を参照してください
• セキュリティパターン：脆弱性の検出と緩和策については modules/sdk-hook-types.md を参照してください
• パフォーマンスガイド：ベンチマークと最適化については modules/evaluation-criteria.md を参照してください

基本的な評価ワークフロー

# 1. Run detailed evaluation
/hooks-eval --detailed

# 2. Focus on security issues
/hooks-eval --security-only --format sarif

# 3. Benchmark performance
/hooks-eval --performance-baseline

# 4. Check compliance
/hooks-eval --compliance-report

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

他のツールとの統合

# Complete plugin evaluation pipeline
/hooks-eval --detailed          # Evaluate all hooks
/analyze-hook hooks/specific.py      # Deep-dive on one hook
/validate-plugin .                   # Validate overall structure

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

関連スキル

• abstract:hook-scope-guide - フックの配置先（プラグイン／プロジェクト／グローバル）を決定する
• abstract:hook-authoring - フックのルールとパターンを作成する
• abstract:validate-plugin - プラグイン全体の構造を検証する

トラブルシューティング

よくある問題

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

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

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

終了基準

• 対象範囲内のすべてのフックについて、重み付けされた次の5つのカテゴリ（セキュリティ（30）、パフォーマンス（25）、コンプライアンス（20）、信頼性（15）、保守性（10））に基づき、総合品質スコア（0～100）が算出されます。
• セキュリティカテゴリのスコアが60未満のフックは、評価レポートを返す前にブロッキング問題として報告されます。
• hooks.json で参照されているシェルコマンドが存在し、実行可能であることを検証します。存在しないスクリプトは FAIL の指摘事項として列挙されます。
• 評価レポートでは、JSON フック（Claude Code）と Python SDK フックを区別し、それぞれの種類に適したシグネチャの要件を適用します。