Claude Code Hook Execution Strategies

Overview

Hooks provide automation triggers at strategic points in Claude Code workflows: pre-tool execution (validation), post-tool execution (processing), and session lifecycle events (initialization, cleanup). Enable systematic enforcement of quality standards and security policies.

Hook Architecture

Three Hook Types

WORKFLOW TIMELINE
│
├─ Session Start
│  └─ SessionStart hooks trigger
│
├─ Tool Invocation
│  ├─ Pre-Tool hooks trigger (validation)
│  ├─ Tool executes
│  └─ Post-Tool hooks trigger (processing)
│
├─ Task Completion
│  └─ SessionEnd hooks trigger (cleanup)
│
└─ Session Close

Hook Types & Timing Models

Pre-Tool Hooks (Validation)

Execute BEFORE tool runs:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/validate-command.py"
          }
        ]
      }
    ]
  }
}

Execution Timing:

User: bash("git commit -m 'message'")
  ↓
Pre-Tool Hook: validate-command.py
  ├─ Check command syntax
  ├─ Verify permissions
  ├─ Scan for dangerous patterns
  └─ Decision: ALLOW / DENY
       ↓
       ALLOW → Tool executes
       DENY → Block & report error

Use Cases:

• Command validation (security)
• Permission checking
• Resource verification
• Input sanitization
• Pattern matching

Example Hook Script:

#!/usr/bin/env python3
import re
import sys
import json

DANGEROUS_PATTERNS = [
    r"rm -rf",
    r"sudo ",
    r"chmod 777",
    r"&&.*rm",
    r"\|.*sh"
]

def validate_command(command):
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command):
            return False, f"Dangerous pattern: {pattern}"
    return True, "Safe"

if __name__ == "__main__":
    input_data = json.load(sys.stdin)
    command = input_data.get("command", "")
    is_safe, message = validate_command(command)

    if not is_safe:
        print(f"SECURITY BLOCK: {message}", file=sys.stderr)
        sys.exit(2)  # Non-zero = block
    sys.exit(0)  # Zero = allow

Post-Tool Hooks (Processing)

Execute AFTER tool completes:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/post-edit-processing.py"
          }
        ]
      }
    ]
  }
}

Execution Timing:

Tool executes: Edit(src/auth.py)
  ↓
Post-Tool Hook: post-edit-processing.py
  ├─ Validate syntax
  ├─ Run linter
  ├─ Check formatting
  └─ Log results
       ↓
Returns to user with processing results

Use Cases:

• Result validation
• Cleanup operations
• Logging and metrics
• Side-effect handling
• Output formatting

Session Hooks (Lifecycle)

Execute at session start/end:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "uv run .moai/scripts/statusline.py"
      }
    ],
    "SessionEnd": [
      {
        "type": "command",
        "command": "python3 .claude/hooks/cleanup.py"
      }
    ]
  }
}

Timing:

SESSION START
  ↓
SessionStart hooks trigger
  ├─ Load project config
  ├─ Initialize memory
  ├─ Check dependencies
  └─ Display status
       ↓
WORK PHASE
       ↓
SESSION END
  ↓
SessionEnd hooks trigger
  ├─ Save state
  ├─ Cleanup temp files
  ├─ Generate report
  └─ Close connections

Use Cases:

• Context initialization
• State setup
• Health checks
• Cleanup on exit
• Report generation

Execution Models

Sequential Execution (Dependent Hooks)

Hooks run one after another, in order:

Tool Call
  ↓
Pre-Hook 1 (VALIDATE INPUT)
  ├─ Check syntax → Pass/Fail
  └─ Output: validated_input
       ↓
Pre-Hook 2 (CHECK PERMISSIONS)
  ├─ Verify permissions → Pass/Fail
  └─ Output: permission_result
       ↓
Pre-Hook 3 (AUDIT LOG)
  ├─ Log operation → Always pass
  └─ Output: audit_entry
       ↓
Tool Execution
  ↓
Post-Hook 1 (VALIDATE OUTPUT)
Post-Hook 2 (FORMAT RESULTS)
Post-Hook 3 (UPDATE METRICS)
  ↓
Result

When to use sequential:

• When hooks depend on previous results
• When order matters (e.g., validation before execution)
• When failure of one hook should block others

Parallel Execution (Independent Hooks)

Hooks run simultaneously when independent:

Tool Call
  ↓
Pre-Hooks (all in parallel):
  ├─ Thread 1: Validate syntax
  ├─ Thread 2: Check permissions
  ├─ Thread 3: Scan for secrets
  └─ Thread 4: Verify resources
       ↓
       (All must pass for tool to execute)
  ↓
Tool Execution
  ↓
Post-Hooks (all in parallel):
  ├─ Thread 1: Validate output
  ├─ Thread 2: Update metrics
  ├─ Thread 3: Log operation
  └─ Thread 4: Format results
  ↓
Result

When to use parallel:

• When hooks are independent
• For performance optimization
• When order doesn't matter
• For I/O operations

Hook Composition & Chaining

Hook Chain Pattern

# Pre-execution chain:
# 1. Validation Hook    (input validation)
# 2. Permission Hook    (authorization)
# 3. Resource Hook      (availability check)
# 4. Audit Hook         (logging)
# 5. Execution         (actual tool)

# Post-execution chain:
# 1. Output Hook        (result validation)
# 2. Processing Hook    (transformation)
# 3. Cleanup Hook       (resource release)
# 4. Metrics Hook       (usage tracking)

Conditional Hook Execution

#!/bin/bash
# Hook only runs if specific conditions met

if [[ "$TOOL_TYPE" == "Edit" ]]; then
  # Run linter for edit operations
  python3 -m pylint --score=no "$FILE" || exit 1
fi

if [[ "$COMMAND" == "rm -rf" ]]; then
  echo "BLOCKED: Destructive command"
  exit 2
fi

exit 0

Error Handling in Hooks

Hook Failure Handling

# Hook exit codes:
# 0 = Success (allow/continue)
# 1 = Warning (log but continue)
# 2 = Error (block/stop)

#!/usr/bin/env python3
import sys

try:
    # Perform validation
    result = validate_operation()
    
    if not result.valid:
        # Block operation
        print(f"BLOCK: {result.error}", file=sys.stderr)
        sys.exit(2)  # Exit code 2 = block
    
except Exception as e:
    # Unexpected error
    print(f"ERROR: {e}", file=sys.stderr)
    sys.exit(1)  # Exit code 1 = warning

# Success
sys.exit(0)  # Exit code 0 = allow

Hook Timeout Handling

{
  "hooks": {
    "PreToolUse": [
      {
        "command": "python3 .claude/hooks/fast-validation.py",
        "timeout": 5000  # 5 second timeout
      }
    ]
  }
}

Best Practices

Hook Design

• ✅ Keep hooks lightweight (< 1 second)
• ✅ Implement proper error handling
• ✅ Use sequential for dependent hooks
• ✅ Use parallel for independent hooks
• ✅ Log hook execution
• ✅ Test hooks thoroughly
• ✅ Document hook purpose

Performance

• ✅ Minimize hook execution time
• ✅ Cache validation results
• ✅ Use parallel execution where possible
• ✅ Avoid blocking I/O in hooks
• ✅ Monitor hook performance

Security

• ✅ Validate all hook inputs
• ✅ Handle edge cases
• ✅ Log security decisions
• ✅ Test with malicious input
• ✅ Use secure exit codes

Common Hook Scenarios

Scenario 1: Pre-Commit Security Check

#!/bin/bash
# Pre-commit hook: validate before git commit

# Check for secrets
if grep -r "PASSWORD\|API_KEY\|SECRET" --include="*.py" . ; then
  echo "ERROR: Secrets found in code"
  exit 2
fi

# Check code formatting
python3 -m black --check . || exit 2

# All checks pass
exit 0

Scenario 2: Post-Edit Code Formatting

#!/bin/bash
# Post-edit hook: auto-format edited files

# Get edited file from input
FILE="$1"

# Auto-format
python3 -m black "$FILE" || exit 1
python3 -m ruff check --fix "$FILE" || exit 1

echo "Formatted: $FILE"
exit 0

Scenario 3: Session Initialization

#!/bin/bash
# SessionStart hook: initialize project context

# Load project status
echo "Loading project configuration..."
python3 .moai/scripts/statusline.py

# Check dependencies
echo "Verifying dependencies..."
uv sync --quiet

echo "Session ready!"
exit 0

TRUST 5 Compliance

• Test-First: Hook patterns tested with real execution scenarios
• Readable: Clear hook structure, well-documented intent, self-explanatory
• Unified: Consistent hook implementation across all types
• Secured: Validation and security hooks, proper error handling
• Trackable: Full hook execution logging and audit trail

Related Skills

• moai-cc-permission-mode - Permission validation in hooks
• moai-cc-subagent-lifecycle - Lifecycle hooks for subagents
• moai-core-workflow - Overall workflow orchestration

Last Updated: 2025-11-19 Version: 4.0.0 Enterprise Production Ready: Yes ✅ Maturity: Stable