Validate Hook

Detailed validation for Claude Code and SDK hooks. Performs security scanning, performance analysis, and compliance verification.

When To Use

Use this command when you need to:

• Developing hooks and need validation before deployment
• Auditing existing hooks for security vulnerabilities
• Checking hook performance and timeout compliance
• Verifying compliance with SDK best practices
• Before committing hook changes

When NOT To Use

Avoid this command if:

• Creating new hooks - use /create-hook instead
• Evaluating all hooks in plugin - use /hooks-eval instead
• Deciding hook placement - use hook-scope-guide skill

Usage

# Validate all aspects (default)
/validate-hook hooks/my-hook.py

# Validate specific aspects
/validate-hook hooks/my-hook.py --security
/validate-hook hooks/my-hook.py --performance
/validate-hook hooks/my-hook.py --compliance

# Validate all hooks in directory
/validate-hook hooks/ --all

# Generate detailed report
/validate-hook hooks/my-hook.py --report

# Auto-fix issues where possible
/validate-hook hooks/my-hook.py --fix

Validation Categories

Security Scan (--security)

Checks for security vulnerabilities and unsafe patterns:

• Input Validation: Type checking, size bounds, sanitization
• Command Injection: Shell command safety, parameter escaping, code injection patterns
• Path Traversal: Path validation, directory restrictions, directory traversal attacks
• Data Leakage: PII handling, credential exposure, hardcoded secrets
• Privilege Escalation: Permission checks, sandboxing, sudo usage, chmod operations
• Crypto Issues: Weak encryption, insecure randomness

Score: PASS (100%), WARN (80-99%), FAIL (<80%)

Performance Check (--performance)

Analyzes hook efficiency and resource usage:

• Timeout Compliance: Execution within limits (1-10s typical)
• Resource Usage: Memory, CPU, file handles
• Blocking Operations: Async patterns, non-blocking I/O
• Caching: Result caching, expensive operation optimization
• Early Exits: Fast-path optimization
• Scalability: Performance under load, large file handling
• Pattern Matching Efficiency: Regex compilation, loop optimization

Score: OPTIMAL (>90%), ACCEPTABLE (70-90%), POOR (<70%)

Compliance Check (--compliance)

Verifies SDK and best practice adherence:

• SDK Version: Compatible with installed version
• Hook Schema: Correct frontmatter, required fields
• Output Format: Valid JSON structure
• Error Handling: Try-catch blocks, graceful failures, proper exit codes
• Logging: Structured logging, appropriate levels
• Scope Appropriateness: Correct hook placement and precedence (plugin/project/global)
• Variable Quoting: Shell variable safety, set operations

Score: COMPLIANT (100%), MINOR ISSUES (95-99%), NON-COMPLIANT (<95%)

Combined Report

VALIDATION REPORT: hooks/pre-tool-use.py
==========================================
SECURITY:     PASS (100%) - No issues found
PERFORMANCE:  WARN (85%)  - Consider async for file I/O
COMPLIANCE:   PASS (100%) - Fully compliant

OVERALL: PASS with 1 warning

Issues Found:
[PERFORMANCE/WARN] Line 45: Synchronous file read
  Impact: May block execution for large files
  Fix: Use async file I/O or implement timeout

Recommendations:
- Consider adding result caching for expensive operations
- Add unit tests for error paths

Exit Codes

• 0: PASS - Hook validated successfully
• 1: WARN - Issues found, review recommended
• 2: FAIL - Critical issues, must fix before deployment

Auto-Fix Mode

/validate-hook hooks/my-hook.py --fix

Automatically applies fixes for common issues:

• Add missing input validation
• Implement timeout guards
• Fix JSON output structure
• Add error handling wrappers

Note: Review auto-fixes before committing.

Detailed Validation Guides

For more validation patterns, see the validate-hook source code and examples in the abstract validation framework.

Best Practices

When to Validate:

• Before every hook commit
• After modifying hook logic
• Before production deployment
• During security audits
• After SDK updates

Score Interpretation:

• 100%: Production ready
• 95-99%: Minor improvements recommended
• 80-94%: Review and fix warnings
• <80%: Critical issues, must fix

Common Patterns:

• Validate inputs at entry points
• Use timeouts for all external operations
• Implement graceful error handling
• Cache expensive computations
• Log security-relevant events