Hooks & Automation

Complete reference for Claude Code hooks, settings, MCP servers, and practical memory augmentation patterns.

All Hook Events

27 total events (source-verified from src/entrypoints/sdk/coreTypes.ts):

Events that CAN Block Actions (exit code 2)

Informational Events (cannot block)

Hook Handler Types

Matcher Patterns

Matchers are regex patterns. What they match depends on the event:

The if Field (source-verified)

Uses permission rule syntax for pre-execution filtering: "if": "Bash(git *)". Key differences from matcher:

• Purpose: Avoids spawning hook processes for non-matching commands (performance)
• Evaluation order: After matcher, before execution
• Scope: Only works for tool events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest)
• Dedup: Hooks with different if conditions are distinct even if otherwise identical

Hook Input/Output

Input (stdin JSON)

All hooks receive a common envelope:

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

Tool events additionally include tool_name, tool_input, and tool_use_id. PostToolUse also includes tool_response.

Output (stdout JSON, exit 0)

{
  "continue": true,
  "stopReason": "Build failed",
  "suppressOutput": false,
  "systemMessage": "Warning text",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "explanation",
    "updatedInput": { "command": "modified command" },
    "additionalContext": "context for Claude"
  }
}

Exit Codes

Context Injection via Hooks

SessionStart Output Fields (source-verified)

SessionStart hooks can return three special fields in hookSpecificOutput:

• additionalContext — injected into Claude's context
• initialUserMessage — sets the first user message
• watchPaths — array of absolute file paths to monitor for FileChanged events

SessionStart: Inject Context at Session Start

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "/path/to/memory-router.sh",
        "timeout": 5000
      }]
    }]
  }
}

PostCompact: Re-inject After Compaction

{
  "hooks": {
    "SessionStart": [{
      "matcher": "compact",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Reminder: always verify claims before acting on them.\"}}'"
      }]
    }]
  }
}

Environment Variable Persistence

The $CLAUDE_ENV_FILE mechanism lets SessionStart hooks persist environment variables across the session:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export PROJECT_TYPE=svelte' >> "$CLAUDE_ENV_FILE"
fi

Key Settings Reference

Configuration Scopes (Precedence: high to low)

1. Managed — /etc/claude-code/managed-settings.json (cannot be overridden)
2. CLI flags — --model, --permission-mode, etc.
3. Local — .claude/settings.local.json (personal, not committed)
4. Project — .claude/settings.json (committed, shared)
5. User — ~/.claude/settings.json (personal, all projects)

Memory-Related Settings (source-verified)

Permission Rule Syntax

MCP Servers for Memory

Configuration

// ~/.claude/.mcp.json (user scope)
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": { "MEMORY_DIR": "/home/visar/.claude/semantic-memory" }
    }
  }
}

Available Memory MCP Servers

Tool definitions are deferred by default — only tool names consume context until used. Check per-server context costs with /mcp.

Path-Scoped Rules

# ~/.claude/rules/svelte-conventions.md
---
paths:
  - "**/+page.svelte"
  - "**/+layout.svelte"
  - "**/*.svelte"
---
# Svelte 5 Rules
- Never use $: reactive statements (Svelte 4 syntax)
- Use $state, $derived, $effect runes
- Never call imperative APIs inside $effect
- Read svelte5-pitfalls.md for full list

# ~/.claude/rules/deploy-safety.md
---
paths:
  - "**/deploy.sh"
  - "**/Dockerfile"
  - "**/.github/workflows/**"
---
# Deployment Rules
- Read hetzner-deploy.md before any deploy changes
- Always test locally before pushing

Practical Patterns

Pattern 1: Dynamic Git Context at Session Start

#!/bin/bash
# Inject git state as context
CONTEXT="Current branch: $(git branch --show-current 2>/dev/null)"
CONTEXT="$CONTEXT\nRecent commits:\n$(git log --oneline -5 2>/dev/null)"
CONTEXT="$CONTEXT\nChanged files:\n$(git diff --name-only 2>/dev/null)"
jq -n --arg ctx "$CONTEXT" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'

Pattern 2: Protect Files from Edits

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
PROTECTED=('.env' 'package-lock.json' '.git/')
for p in "${PROTECTED[@]}"; do
  if [[ "$FILE" == *"$p"* ]]; then
    echo "Blocked: $FILE matches protected pattern $p" >&2
    exit 2
  fi
done
exit 0

Pattern 3: Auto-format After File Writes

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$FILE" ;;
  *.py) black "$FILE" ;;
esac
exit 0

Pattern 4: Always-On Behavioral Rules via SessionStart

#!/bin/bash
# Inject universal rules that apply to every coding task
RULES="ALWAYS-ON RULES:
1. One fix at a time - only implement the specific approved change
2. Verify claims - label uncertain statements as 'Claim:' and offer to verify
3. Evidence first - debug from logs/data, never speculation
4. No magic strings - use constants or enums for property checks
5. Timebox debugging to ~1h, then build a minimal reproduction"

jq -n --arg ctx "$RULES" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'