Agent skill

moai-cc-hook-model-strategy

Claude Code hook execution strategies, timing models, sequencing patterns, and orchestration for automated workflow enforcement. Covers all hook types and execution timing models.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/moai-cc-hook-model-strategy

SKILL.md

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:

json
{
  "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:

python
#!/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:

json
{
  "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:

json
{
  "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

python
# 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

bash
#!/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

python
# 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

json
{
  "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

bash
#!/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

bash
#!/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

bash
#!/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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results