/hooks-eval

name: hooks-eval
description: Evaluate all hooks in a plugin for quality and compliance
usage: /hooks-eval [plugin-path] [options]

Hooks-Eval

Detailed evaluation framework for analyzing all hooks within a plugin (or across project/global scopes) with advanced security scanning, performance benchmarking, and compliance validation. Built on the same principles as skills-eval but specifically tailored for Claude Code hook architecture.

When To Use

Use this command when you need to:

• Evaluating all hooks in a plugin comprehensively
• Comparing multiple hooks
• Validating quality gates across hook portfolio
• Security scanning entire plugin's hooks

When NOT To Use

Avoid this command if:

• Validating specific hook - use /validate-hook instead
• Creating new hooks - use /create-hook instead

Usage

# Evaluate all hooks in current plugin
/hooks-eval

# Evaluate specific plugin directory
/hooks-eval /path/to/plugin

# Security-focused evaluation
/hooks-eval --security-only

# Performance benchmarking
/hooks-eval --performance-baseline

# Compliance checking
/hooks-eval --compliance-report

# Generate detailed report
/hooks-eval --detailed --format detailed

# Cross-scope evaluation (plugin → project → global)
/hooks-eval --all-scopes

# CI/CD integration
/hooks-eval --quality-gate --format json --output results.json

Options

Scope Selection

• `--plugin <path>`: Specific plugin directory (default: current plugin)
• `--scope <type>`: Evaluate specific scope (plugin, project, global)
• `--all-scopes`: Evaluate all scopes in priority order
• `--include-external`: Include hooks from external dependencies

Analysis Focus

• `--security-only`: Focus exclusively on security vulnerabilities
• `--performance-check`: Analyze execution performance and resource usage
• `--compliance-check`: Validate against hook development standards
• `--detailed`: Full analysis across all dimensions (default)

Output Control

• `--format <type>`: Output format (summary, detailed, json, sarif, dashboard)
• `--output <file>`: Write results to file
• `--verbose`: Show detailed analysis and recommendations
• `--quiet`: Minimal output, exit codes only
• `--severity <level>`: Minimum severity level to report

Quality Gates

• `--quality-gate`: Enable quality gate checking with thresholds
• `--fail-on <level>`: Fail exit on specific severity level
• `--baseline <file>`: Compare against previous evaluation baseline

Evaluation Framework

Scoring System (100 points total)

**Security Analysis (30 points)**

• Critical vulnerabilities: -15 points each
• High-risk issues: -8 points each
• Medium-risk issues: -4 points each
• Low-risk issues: -1 point each

**Performance Analysis (25 points)**

• Execution time efficiency: 10 points
• Memory usage optimization: 8 points
• I/O operation efficiency: 4 points
• Resource cleanup: 3 points

**Compliance Analysis (20 points)**

• Structure compliance: 8 points
• Documentation completeness: 6 points
• Error handling: 4 points
• Best practices: 2 points

**Reliability Analysis (15 points)**

• Error handling robustness: 6 points
• Timeout management: 4 points
• Idempotency: 3 points
• Graceful degradation: 2 points

**Maintainability (10 points)**

• Code structure: 4 points
• Documentation clarity: 3 points
• Modularity: 2 points
• Test coverage: 1 point

Quality Levels

• **91-100**: Excellent - Production-ready, follows all best practices
• **76-90**: Good - Minor improvements suggested
• **51-75**: Acceptable - Some issues requiring attention
• **26-50**: Poor - Significant issues need addressing
• **0-25**: Critical - Major security or reliability issues

Output Examples

Basic Evaluation

/hooks-eval
# === Hooks Evaluation Report ===
# Plugin: abstract (v1.0.0)
# Scope: Plugin hooks only
# Total hooks found: 5 (4 JSON, 1 Python script)
#
# === Overall Scores ===
# Security Score: 82/100 (Good)
# Performance Score: 78/100 (Good)
# Compliance Score: 85/100 (Good)
# Reliability Score: 88/100 (Good)
# Maintainability Score: 75/100 (Good)
# Overall Score: 81/100 (Good)
#
# === Critical Issues ===
# [CRITICAL] hooks/gemini/bridge.on_tool_start:23 - eval() with user input
#
# === Recommendations ===
# 1. Replace eval() with JSON parsing for security
# 2. Add timeout configuration to JSON hooks
# 3. Implement input validation for all script hooks

Security-Only Evaluation

/hooks-eval --security-only --format sarif
# {
#   "version": "2.1.0",
#   "runs": [{
#     "tool": {"name": "hooks-eval"},
#     "results": [
#       {
#         "ruleId": "command-injection",
#         "level": "error",
#         "message": {"text": "Use of eval() with user input"},
#         "locations": [{
#           "physicalLocation": {
#             "artifactLocation": {"uri": "hooks/gemini/bridge.on_tool_start"},
#             "region": {"startLine": 23}
#           }
#         }]
#       }
#     ]
#   }]
# }

Performance Benchmarking

/hooks-eval --performance-baseline --format detailed
# === Performance Analysis ===
# Hook Performance Benchmarks:
#
# hooks/pre-skill-load.json:
#   Estimated execution: 15ms (threshold: 100ms) OK
#   Memory usage: 2MB (threshold: 50MB) OK
#   I/O operations: 0 (minimal) OK
#
# hooks/post-evaluation.json:
#   Estimated execution: 25ms (threshold: 200ms) OK
#   Memory usage: 5MB (threshold: 100MB) OK
#   Complex logic: Medium complexity [WARN]
#
# hooks/gemini/bridge.on_tool_start:
#   Estimated execution: 180ms (threshold: 100ms)
#   Memory usage: 45MB (threshold: 50MB) [WARN]
#   File I/O: Multiple stat() calls [WARN]
#
# === Performance Recommendations ===
# 1. Optimize gemini bridge hook for better performance
# 2. Cache file statistics to reduce system calls
# 3. Consider async processing for large file operations

Integration with Other Tools

CI/CD Integration

# GitHub Actions example
- name: Evaluate Hooks
  run: |
    /hooks-eval --quality-gate --format js