Claude Code Hooks Deep Dive: PreToolUse, PostEdit, and PreCompact for Zero-Drift Agentic Codebases

stateDiagram-v2
    [*] --> PromptIngress: User Types Command
    
    state Claude_Reasoning_Loop {
        PromptIngress --> PreToolUse_Hook: Claude decides to invoke tool
        
        state PreToolUse_Hook {
            [*] --> Inspect_Tool_Payload
            Inspect_Tool_Payload --> Decision: Evaluate Rules
            Decision --> Exit_0_Allow: Allowed
            Decision --> Exit_2_Block: Denied (Security Risk)
        }
        
        Exit_2_Block --> PromptIngress: Injects Stderr Remediation into Context
        Exit_0_Allow --> Host_Tool_Execution: Executes Bash/FileEdit/Grep
        
        Host_Tool_Execution --> PostToolUse_Hook: Tool finishes
        PostToolUse_Hook --> Run_Linter_Pytest: Runs PostEdit / PostTool Checks
        Run_Linter_Pytest --> Model_Next_Turn: Feeds tool result + hook stdout
    }
    
    Model_Next_Turn --> Context_Threshold_Check: Context approaches 180k tokens
    
    state Compaction_Phase {
        Context_Threshold_Check --> PreCompact_Hook: Trigger before lossy compression
        PreCompact_Hook --> Stream_History_To_Disk: Zero-token raw transcript backup
        Stream_History_To_Disk --> LLM_Compaction_Engine: Summarizes memory
        LLM_Compaction_Engine --> PostCompact_Hook: Re-inject critical invariant pointers
    }
    
    PostCompact_Hook --> Model_Next_Turn
    Model_Next_Turn --> Stop_Hook: Session complete / User exit
    Stop_Hook --> Notification_Hook: Webhook / Slack alert
    Notification_Hook --> [*]

┌──────────────────┐
│  EXIT CODE 0     │ ──► ALLOW / SUCCESS: Hook executed cleanly.
│                  │     Stdout (if any) is optionally injected into the LLM context.
└──────────────────┘

┌──────────────────┐
│  EXIT CODE 2     │ ──► HARD BLOCK / POLICY VIOLATION:
│                  │     The tool call is CANCELLED immediately.
│                  │     The tool is NOT executed.
│                  │     Stderr is fed directly to Claude as a high-priority system error.
└──────────────────┘

┌──────────────────┐
│  EXIT CODE 1 / >2│ ──► INTERNAL SCRIPT ERROR:
│                  │     The hook itself crashed. Claude CLI logs a warning and proceeds.
└──────────────────┘

# Example Stderr Emitted by Hook:
"SECURITY ERROR: Direct push to 'main' is forbidden by organizational policy.
Please create a feature branch: git checkout -b feat/your-feature"

#!/usr/bin/env python3
"""
Enterprise PreToolUse Security Interceptor for Claude Code.
Intercepts destructive bash commands, database drops, and API key exposures.
Author: Vatsal Shah (2026)
"""

import sys
import json
import re

# Blacklisted destructive command patterns
FORBIDDEN_BASH_PATTERNS = [
    (r"rm\s+-(rf|fr)\s+[/~]", "Recursive deletion of root or home directory is blocked."),
    (r"drop\s+database", "Direct SQL DROP DATABASE command is forbidden. Use migration rollbacks."),
    (r"git\s+push\s+.*(--force|-f)\s+.*(main|master|production)", "Force pushing to protected branches is blocked."),
    (r":(){ :|:& };:", "Fork bomb syntax detected and blocked."),
    (r"chmod\s+-R\s+777", "Insecure recursive 777 permissions blocked.")
]

# Sensitive credential patterns
SECRET_PATTERNS = [
    (r"ghp_[A-Za-z0-9_]{36}", "GitHub Personal Access Token detected in arguments."),
    (r"sk-[A-Za-z0-9-_]{32,}", "OpenAI API Key detected in arguments."),
    (r"xox[baprs]-[A-Za-z0-9-]+", "Slack API Token detected in arguments.")
]


def evaluate_payload():
    try:
        raw_input = sys.stdin.read()
        if not raw_input.strip():
            sys.exit(0)
            
        payload = json.loads(raw_input)
    except Exception as e:
        # Fail open or closed based on enterprise policy (Closed recommended for high-sec)
        sys.stderr.write(f"PreToolUse Parse Warning: {str(e)}\n")
        sys.exit(0)

    tool_name = payload.get("tool_name", "")
    tool_input = payload.get("tool_input", {})

    # Inspect Bash Commands
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        
        # Check Destructive Patterns
        for pattern, explanation in FORBIDDEN_BASH_PATTERNS:
            if re.search(pattern, command, re.IGNORECASE):
                sys.stderr.write(f"🛑 SECURITY INTERCEPTOR BLOCKED COMMAND:\n{explanation}\n")
                sys.stderr.write(f"Attempted Command: {command}\n")
                sys.stderr.write("Remediation: Modify your command to avoid destructive operations.\n")
                sys.exit(2)  # Hard Block

        # Check Secret Leakage
        for pattern, explanation in SECRET_PATTERNS:
            if re.search(pattern, command):
                sys.stderr.write(f"🛑 SECURITY INTERCEPTOR DETECTED LEAKED SECRET:\n{explanation}\n")
                sys.exit(2)

    # Inspect File Edits on Protected Files
    if tool_name in ["FileEdit", "WriteFile"]:
        target_path = tool_input.get("target_file", "") or tool_input.get("path", "")
        if target_path.endswith((".env.production", "secrets.json", "id_rsa")):
            sys.stderr.write(f"🛑 BLOCKED WRITE TO RESTRICTED FILE: {target_path}\n")
            sys.stderr.write("Remediation: Production secrets must be managed via HashiCorp Vault / AWS Secrets Manager.\n")
            sys.exit(2)

    # All checks passed cleanly
    sys.exit(0)


if __name__ == "__main__":
    evaluate_payload()

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "tool_name == 'FileEdit' || tool_name == 'WriteFile'",
        "command": "bash .claude/hooks/post_edit_linter.sh"
      }
    ]
  }
}

#!/usr/bin/env bash
# Fast PostEdit Hook: Automatically lints modified file and runs targeted test
set -e

# Read JSON payload from stdin
PAYLOAD=$(cat)
TARGET_FILE=$(echo "$PAYLOAD" | jq -r '.tool_input.target_file // .tool_input.path // empty')

if [ -z "$TARGET_FILE" ] || [ ! -f "$TARGET_FILE" ]; then
    exit 0
fi

# 1. Auto-format JavaScript / TypeScript files
if [[ "$TARGET_FILE" =~ \.(ts|tsx|js|jsx)$ ]]; then
    npx prettier --write "$TARGET_FILE" > /dev/null 2>&1 || true
    npx eslint --fix "$TARGET_FILE" > /dev/null 2>&1 || true
fi

# 2. Auto-format Python files
if [[ "$TARGET_FILE" =~ \.py$ ]]; then
    ruff format "$TARGET_FILE" > /dev/null 2>&1 || true
    ruff check --fix "$TARGET_FILE" > /dev/null 2>&1 || true
fi

# 3. Targeted Test Execution (Fast Feedback Loop)
if [[ "$TARGET_FILE" =~ app/services/(.*)\.py ]]; then
    MODULE_NAME="${BASH_REMATCH[1]}"
    TEST_FILE="tests/unit/test_${MODULE_NAME}.py"
    if [ -f "$TEST_FILE" ]; then
        echo "Running fast test suite: $TEST_FILE"
        pytest -q "$TEST_FILE" || {
            echo "⚠️ Auto-Test Failed after edit on $TARGET_FILE. Stderr emitted to Claude for immediate self-repair."
            exit 0 # Exit 0 so output is fed as context back to Claude
        }
    fi
fi

exit 0

#!/usr/bin/env python3
"""
PreCompact Memory Preservation Hook.
Backups full conversational history and code diffs before lossy compaction.
"""

import sys
import json
import os
import time

MEMORY_DIR = os.path.expanduser(".claude/memory")
os.makedirs(MEMORY_DIR, exist_ok=True)

def archive_session():
    try:
        raw_payload = sys.stdin.read()
        if not raw_payload.strip():
            sys.exit(0)
        
        data = json.loads(raw_payload)
        session_id = data.get("session_id", f"session_{int(time.time())}")
        archive_path = os.path.join(MEMORY_DIR, f"{session_id}_precompact_archive.jsonl")

        with open(archive_path, "a", encoding="utf-8") as f:
            f.write(json.dumps({
                "timestamp": time.time(),
                "event": "PreCompact",
                "payload": data
            }) + "\n")

        print(f"[PreCompact Memory Hook] Raw transcript preserved to: {archive_path}")
    except Exception as e:
        sys.stderr.write(f"PreCompact Backup Error: {str(e)}\n")

    sys.exit(0)

if __name__ == "__main__":
    archive_session()

Central Security Policy Repository (git.internal/security/claude-guardrails)
  │
  ├─► Phase 1: Machine Deployment (MDM / Homebrew / Dotfiles)
  │     • Symlinks global `~/.claude/hooks.json` to protected root
  │     • Enforces read-only permissions on security interceptor scripts
  │
  ├─► Phase 2: Local Developer Runtime Execution
  │     • PreToolUse blocks prohibited bash commands & credential leaks
  │     • PostToolUse auto-formats code with corporate ESLint / Ruff standards
  │     • PreCompact archives session history for engineering audit logs
  │
  └─► Phase 3: Centralized OpenTelemetry Security & Audit Spans
        • All blocked actions stream structured logs to ClickHouse / Splunk
        • Automated alerts trigger if developer machines encounter repeated `exit 2` blocks