Claude Code Hooks: 10 Examples for Logging, Safety and Costs

{
  "hooks": {
    "PreToolUse": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tools.py"], "timeout": 5
    }]}],
    "PostToolUse": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tools.py"], "timeout": 5
    }]}],
    "PostToolUseFailure": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tools.py"], "timeout": 5
    }]}]
  }
}

import fcntl
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
 
os.umask(0o077)
data = json.load(sys.stdin)
fields = ("session_id", "prompt_id", "hook_event_name", "tool_name",
          "tool_use_id", "agent_id", "agent_type", "duration_ms")
entry = {key: data[key] for key in fields if key in data}
entry["timestamp"] = datetime.now(timezone.utc).isoformat()
entry["has_error"] = "error" in data
folder = Path.home() / ".claude" / "hook-logs"
folder.mkdir(parents=True, exist_ok=True)
with (folder / "tool-events.jsonl").open("a", encoding="utf-8") as log:
    fcntl.flock(log.fileno(), fcntl.LOCK_EX)
    log.write(json.dumps(entry, separators=(",", ":")) + "\n")
    log.flush()

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.py"], "timeout": 5
    }]}]
  }
}

import json
import re
import sys
 
try:
    data = json.load(sys.stdin)
    command = data["tool_input"]["command"]
    if not isinstance(command, str):
        raise ValueError("command is not text")
except (ValueError, KeyError, TypeError):
    print("Cannot validate this command: invalid hook input.", file=sys.stderr)
    sys.exit(2)
 
reason = None
for match in re.finditer(r"\brm\s+((?:(?:--[\w-]+|-[A-Za-z]+)\s+)+)", command):
    options = match.group(1).split()
    flags = "".join(option[1:] for option in options
                    if not option.startswith("--"))
    recursive = "r" in flags or "R" in flags or "--recursive" in options
    forced = "f" in flags or "--force" in options
    if recursive and forced:
        reason = "Recursive force removal is blocked. Remove specific files or ask the user."
        break
if re.search(r"\bgit\b[^\n]*\bpush\b[^\n]*(?:--force(?:-with-lease)?\b|\s-[A-Za-z]*f[A-Za-z]*(?:\s|$))", command):
    reason = "Force pushes are blocked. Use a normal push or ask the user."
if reason:
    print(reason, file=sys.stderr)
    sys.exit(2)

{
  "permissions": {
    "deny": [
      "Read(//**/.env*)", "Edit(//**/.env*)",
      "Read(//**/secrets/**)", "Edit(//**/secrets/**)",
      "Read(~/.ssh/**)", "Edit(~/.ssh/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [{"matcher": "Read|Edit|Write|NotebookEdit", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-secrets.py"], "timeout": 5
    }]}]
  }
}

import json
import sys
from pathlib import Path
 
try:
    data = json.load(sys.stdin)
    tool_input = data["tool_input"]
    if not isinstance(tool_input, dict):
        raise ValueError("invalid tool input")
    raw = tool_input.get("file_path") or tool_input.get("notebook_path")
    if not isinstance(raw, str) or not raw:
        raise ValueError("missing path")
    path = Path(raw).expanduser()
    if not path.is_absolute():
        path = Path(data["cwd"]) / path
    candidates = (path, path.resolve())
except (ValueError, KeyError, TypeError, OSError, RuntimeError):
    print("Cannot validate the target file path.", file=sys.stderr)
    sys.exit(2)
for candidate in candidates:
    parts = {part.lower() for part in candidate.parts}
    name = candidate.name.lower()
    if (name == ".env" or name.startswith(".env.") or
            candidate.suffix.lower() in {".pem", ".key"} or
            name in {"id_rsa", "id_ed25519", "credentials.json"} or
            parts.intersection({"secrets", ".ssh"})):
        print("Secret-file access is blocked by project policy.", file=sys.stderr)
        sys.exit(2)

{
  "hooks": {
    "PostToolUse": [{"matcher": "Edit|Write", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/format-file.py"], "timeout": 40
    }]}]
  }
}

import json
import shutil
import subprocess
import sys
from pathlib import Path
 
 
def report(message):
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PostToolUse", "additionalContext": message
    }}))
 
 
data = json.load(sys.stdin)
try:
    file = Path(data["tool_input"]["file_path"]).resolve()
    if not file.is_file() or file.suffix not in {".js", ".jsx", ".ts", ".tsx", ".py", ".pyi"}:
        sys.exit(0)
    repo = subprocess.run(["git", "rev-parse", "--show-toplevel"],
                          cwd=data["cwd"], capture_output=True, text=True, timeout=5)
    if repo.returncode:
        sys.exit(0)
    root = Path(repo.stdout.strip()).resolve()
    relative = file.relative_to(root)
    if set(relative.parts) & {".git", "node_modules", "dist", "build"}:
        sys.exit(0)
    if file.suffix in {".py", ".pyi"}:
        argv = [shutil.which("ruff") or "ruff", "format", "--force-exclude", str(file)]
    else:
        cli = root / "node_modules/prettier/bin/prettier.cjs"
        argv = ["node", str(cli), "--write", "--ignore-unknown", str(file)]
    result = subprocess.run(argv, cwd=root, capture_output=True, text=True, timeout=30)
    if result.returncode:
        report("Formatter failed. Check its installation and configuration, then rerun it.")
except (OSError, ValueError, subprocess.TimeoutExpired):
    report("Formatter did not complete; the edit already happened.")

{
  "hooks": {
    "Stop": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-stop.py"], "timeout": 120
    }]}]
  }
}

import json
import subprocess
import sys
 
 
def block(reason):
    print(json.dumps({"decision": "block", "reason": reason}))
 
 
data = json.load(sys.stdin)
if data.get("stop_hook_active") or data.get("background_tasks"):
    sys.exit(0)
try:
    repo = subprocess.run(["git", "rev-parse", "--show-toplevel"],
                          cwd=data["cwd"], capture_output=True, text=True, timeout=5)
    if repo.returncode:
        sys.exit(0)
    root = repo.stdout.strip()
    status = subprocess.run(["git", "--no-optional-locks", "status", "--porcelain"],
                            cwd=root, capture_output=True, text=True, timeout=5)
    if status.returncode:
        block("Could not inspect the working tree. Check Git before reporting completion.")
        sys.exit(0)
    if not status.stdout:
        sys.exit(0)
    check = subprocess.run(["npm", "run", "check:agent"], cwd=root,
                           capture_output=True, text=True, timeout=100)
    if check.returncode:
        output = (check.stdout + check.stderr)[-3000:]
        block("Project checks failed. Fix or explain the blocker, then rerun checks.\n" + output)
except (OSError, subprocess.TimeoutExpired):
    block("Project checks could not finish. Inspect dependencies, timeout and check:agent.")

{
  "hooks": {
    "Notification": [{"matcher": "permission_prompt|idle_prompt", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/notify.py"], "timeout": 5
    }]}]
  }
}

import json
import shutil
import subprocess
import sys
 
json.load(sys.stdin)
try:
    if sys.platform == "darwin":
        argv = ["osascript", "-e",
                'display notification "Claude Code needs your attention" with title "Claude Code"']
    elif shutil.which("notify-send"):
        argv = ["notify-send", "Claude Code", "Claude Code needs your attention"]
    else:
        print(json.dumps({"terminalSequence": "\u0007"}))
        sys.exit(0)
    result = subprocess.run(argv, capture_output=True, timeout=3)
    if result.returncode:
        print(json.dumps({"terminalSequence": "\u0007"}))
except (OSError, subprocess.TimeoutExpired):
    print(json.dumps({"terminalSequence": "\u0007"}))

{
  "hooks": {
    "SessionStart": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/git-context.py"], "timeout": 15
    }]}]
  }
}

import json
import subprocess
import sys
 
 
data = json.load(sys.stdin)
parts = []
checks = [
    ("Current branch", ["git", "branch", "--show-current"]),
    ("Working tree", ["git", "--no-optional-locks", "status", "--short"]),
    ("Recent commits", ["git", "log", "--oneline", "-5"])
]
for label, argv in checks:
    try:
        result = subprocess.run(argv, cwd=data["cwd"], capture_output=True,
                                text=True, timeout=3)
        if result.returncode == 0:
            parts.append(label + ":\n" + (result.stdout.strip()[:1800] or "(empty)"))
    except (OSError, subprocess.TimeoutExpired):
        pass
if parts:
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "SessionStart", "additionalContext": "\n\n".join(parts)
    }}))

{
  "hooks": {
    "UserPromptSubmit": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-prompt.py"], "timeout": 5
    }]}]
  }
}

import json
import re
import sys
 
 
def block(reason):
    print(json.dumps({
        "decision": "block", "reason": reason,
        "hookSpecificOutput": {
            "hookEventName": "UserPromptSubmit", "suppressOriginalPrompt": True
        }
    }))
 
 
try:
    prompt = json.load(sys.stdin)["prompt"]
    if not isinstance(prompt, str):
        raise ValueError("prompt is not text")
except (ValueError, KeyError, TypeError):
    block("Prompt validation could not run.")
    sys.exit(0)
patterns = [
    r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----",
    r"\bAKIA[0-9A-Z]{16}\b",
    r"\bghp_[A-Za-z0-9]{30,}\b",
    r"\bsk-(?:ant-)?[A-Za-z0-9_-]{24,}\b"
]
if any(re.search(pattern, prompt) for pattern in patterns):
    block("Possible credential detected. Remove it, use a redacted placeholder and rotate exposed credentials.")

{
  "hooks": {
    "SessionStart": [{"matcher": "resume|fork", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/cache-cost.py"], "timeout": 5
    }]}],
    "PreModelSwitch": [{"hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/cache-cost.py"], "timeout": 5
    }]}]
  }
}

import fcntl
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
 
os.umask(0o077)
data = json.load(sys.stdin)
estimate = data.get("estimated_cache_write_usd")
if isinstance(estimate, bool) or not isinstance(estimate, (int, float)):
    sys.exit(0)
keys = ("session_id", "hook_event_name", "source", "model", "from_model",
        "to_model", "context_tokens", "prompt_cache_likely_expired",
        "prompt_cache_warm", "cache_ttl", "pricing", "estimated_cache_write_usd")
entry = {key: data[key] for key in keys if key in data}
entry["timestamp"] = datetime.now(timezone.utc).isoformat()
folder = Path.home() / ".claude" / "hook-logs"
folder.mkdir(parents=True, exist_ok=True)
with (folder / "cache-cost-estimates.jsonl").open("a", encoding="utf-8") as log:
    fcntl.flock(log.fileno(), fcntl.LOCK_EX)
    log.write(json.dumps(entry) + "\n")
    log.flush()

{
  "hooks": {
    "PreCompact": [{"matcher": "manual|auto", "hooks": [{
      "type": "command", "command": "python3",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/backup-transcript.py"], "timeout": 15
    }]}]
  }
}

import json
import os
import shutil
import sys
import time
from pathlib import Path
 
os.umask(0o077)
data = json.load(sys.stdin)
if not data.get("transcript_path"):
    sys.exit(0)
source = Path(data["transcript_path"]).expanduser()
if not source.is_file():
    sys.exit(0)
try:
    folder = Path.home() / ".claude" / "transcript-backups" / str(time.time_ns())
    folder.mkdir(parents=True)
    shutil.copyfile(source, folder / "transcript.jsonl")
except OSError:
    print("Transcript snapshot failed; compaction can continue.", file=sys.stderr)
    sys.exit(1)