Hooks: Event-Driven Automation for Claude Code Sessions

Without hooks, every agent session starts from zero: no context from yesterday’s work, no automatic formatting after edits, no guardrails preventing a blind git push. Hooks are ECC’s event-driven automation layer — shell commands, HTTP calls, or sub-prompts that execute at precise moments in the harness lifecycle, injecting consistent behaviour into every session without requiring manual intervention.

How Hooks Work

The execution pipeline for every tool call passes through the hook graph:

User request
  → Claude picks a tool
    → PreToolUse hooks run   (can block with exit code 2)
      → Tool executes
        → PostToolUse hooks run  (analysis, formatting, feedback)
          → Claude responds
            → Stop hooks run     (audits, session persistence)

Session-boundary hooks (SessionStart, SessionEnd, PreCompact) fire outside the per-tool flow.

PreToolUse hooks run before the tool executes. They can block the call (exit code 2) or emit a warning (write to stderr, exit 0).
PostToolUse hooks run after the tool completes. They can analyze output but cannot block.
Stop hooks run after each complete Claude response.
SessionStart / SessionEnd hooks run at session lifecycle boundaries.
PreCompact hooks run before context compaction — the right moment to save state.

Supported Hook Events

All 18 hook event types defined in schemas/hooks.schema.json:

SessionStart

Session opens. Used to load bounded prior context and detect project state.

UserPromptSubmit

Fires when a user message is submitted. Runs before Claude processes it.

PreToolUse

Before any tool executes. The primary gate for quality checks and blockers.

PermissionRequest

When the harness requests elevated permissions for an operation.

PostToolUse

After a tool completes successfully. Used for formatting, logging, feedback.

PostToolUseFailure

After a tool fails. Used for error analysis and recovery signals.

Notification

Harness notification events (desktop alerts, external integrations).

SubagentStart

Before a sub-agent begins a delegated task.

Stop

After each complete Claude response. Used for audits and session persistence.

SubagentStop

After a sub-agent finishes its delegated task.

PreCompact

Before context compaction. The correct moment to save session state.

InstructionsLoaded

After CLAUDE.md / rules files are loaded into the session context.

TeammateIdle

A teammate agent becomes idle in a multi-agent session.

TaskCompleted

A discrete task unit is marked complete.

ConfigChange

ECC configuration or settings change during a session.

WorktreeCreate

A new git worktree is created for parallel agent work.

WorktreeRemove

A git worktree is removed after parallel work completes.

SessionEnd

Session closes. Used for final cleanup and end markers.

Three Hook Action Types

Every hook entry uses one of three type values:

command
http
prompt / agent

Runs a local shell command. The most common type — shell scripts or Node.js one-liners that receive tool input as JSON on stdin and return JSON on stdout.

{
  "type": "command",
  "command": "node scripts/hooks/my-check.js",
  "async": false,
  "timeout": 30
}

Set "async": true for background hooks that should not block the main flow (e.g., build analysis, cost telemetry).

POSTs tool event data to a URL. Useful for logging to external services, triggering CI webhooks, or notifying dashboards.

{
  "type": "http",
  "url": "https://your-service.example.com/hook",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"],
  "timeout": 15
}

Triggers a sub-prompt or agent invocation. Used when the hook logic requires language-model reasoning rather than deterministic shell execution.

{
  "type": "prompt",
  "prompt": "Review the last edit for potential security vulnerabilities and summarize findings.",
  "model": "claude-haiku-4-5",
  "timeout": 60
}

Hook Definition Structure

A complete hooks configuration file maps event names to arrays of matcher entries:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "description": "Tmux reminder for long-running commands",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -z \"$TMUX\" ]; then echo '[Hook] Consider tmux for session persistence' >&2; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "description": "Auto-format JS/TS files with Prettier after edits",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/prettier-format.js"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/session-start.js"
          }
        ]
      }
    ]
  }
}

Exit codes for command hooks:

Code	Meaning
`0`	Success — continue execution
`2`	Block the tool call (`PreToolUse` only)
Other non-zero	Error — logged but does not block

ECC Built-In Hooks

PreToolUse Hooks

Hook	Matcher	Behavior	Exit Code
Dev server blocker	`Bash`	Blocks `npm run dev` etc. outside tmux — ensures log access	2 (blocks)
Tmux reminder	`Bash`	Suggests tmux for long-running commands (`npm test`, `cargo build`, `docker`)	0 (warns)
Git push reminder	`Bash`	Reminds to review changes before `git push`	0 (warns)
Pre-commit quality check	`Bash`	Lints staged files, validates commit message format, detects `console.log` / debugger / secrets	2 (blocks critical) / 0 (warns)
Doc file warning	`Write`	Warns about non-standard `.md`/`.txt` files; allows README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SKILL, `docs/`, `skills/`	0 (warns)
Strategic compact	`Edit\|Write`	Suggests manual `/compact` at logical intervals (~every 50 tool calls)	0 (warns)
Config protection	`Write\|Edit\|MultiEdit`	Blocks modifications to linter/formatter config files — steers agent to fix code instead	2 (blocks)

PostToolUse Hooks

Hook	Matcher	What It Does
PR logger	`Bash`	Logs PR URL and review command after `gh pr create`
Build analysis	`Bash`	Background analysis after build commands (async, non-blocking)
Quality gate	`Edit\|Write\|MultiEdit`	Runs fast quality checks after edits
Design quality check	`Edit\|Write\|MultiEdit`	Warns when frontend edits drift toward generic template-looking UI
Prettier format	`Edit`	Auto-formats JS/TS files with Prettier after edits
TypeScript check	`Edit`	Runs `tsc --noEmit` after editing `.ts`/`.tsx` files
console.log warning	`Edit`	Warns about `console.log` statements in edited files

Lifecycle Hooks

Hook	Event	What It Does
Session start	`SessionStart`	Loads previous context and detects package manager
Pre-compact	`PreCompact`	Saves state before context compaction
Console.log audit	`Stop`	Checks all modified files for `console.log` after each response
Session summary	`Stop`	Persists session state when transcript path is available
Pattern extraction	`Stop`	Evaluates session for extractable patterns (continuous learning)
Cost tracker	`Stop`	Emits lightweight run-cost telemetry markers
Desktop notify	`Stop`	Sends macOS desktop notification with task summary
Session end marker	`SessionEnd`	Lifecycle marker and cleanup log

Installing Hooks

# Install the full hooks-runtime module
npx ecc install --modules hooks-runtime --target claude
# Hooks are written to ~/.claude/hooks/hooks.json

# On Windows
npx ecc install --modules hooks-runtime --target claude
# Hooks are written to %USERPROFILE%\.claude\hooks\hooks.json

Do not paste the raw repo hooks.json directly into ~/.claude/settings.json. The checked-in file is plugin-oriented and uses relative paths. Use the installer so hook commands are rewritten against your actual Claude root.

Runtime Hook Controls

You can tune hook behaviour without editing hooks.json using environment variables:

# Profile: minimal | standard | strict (default: standard)
export ECC_HOOK_PROFILE=standard

# Disable specific hook IDs (comma-separated)
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Disable GateGuard (dev-server blocker) during setup or recovery
export ECC_GATEGUARD=off

# Cap SessionStart additional context (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart additional context entirely
export ECC_SESSION_START_CONTEXT=off

# Suppress API-rate cost estimate warnings
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Profile	Description
`minimal`	Essential lifecycle and safety hooks only
`standard`	Default — balanced quality and safety checks
`strict`	Additional reminders and stricter guardrails

Writing a Custom Hook

Hooks receive tool input as JSON on stdin and must return JSON on stdout.

// my-hook.js
let data = '';
process.stdin.on('data', chunk => data += chunk);
process.stdin.on('end', () => {
  const input = JSON.parse(data);

  const toolName  = input.tool_name;    // "Edit", "Bash", "Write", etc.
  const toolInput = input.tool_input;   // tool-specific parameters
  // input.tool_output is available in PostToolUse hooks only

  // Warn (non-blocking): write to stderr
  if (/TODO|FIXME/.test(toolInput.new_string || '')) {
    console.error('[Hook] New TODO added — consider creating an issue');
  }

  // Block (PreToolUse only): exit with code 2
  // process.exit(2);

  // Always forward the original data to stdout
  console.log(data);
});

For hooks that should run without blocking the main flow, set "async": true in the hook definition:

{
  "type": "command",
  "command": "node my-slow-hook.js",
  "async": true,
  "timeout": 30
}

Getting Started

Core Concepts

Using ECC

Security

Hooks: Event-Driven Automation for Claude Code Sessions

How Hooks Work

Supported Hook Events

SessionStart

UserPromptSubmit

PreToolUse

PermissionRequest

PostToolUse

PostToolUseFailure

Notification

SubagentStart

Stop

SubagentStop

PreCompact

InstructionsLoaded

TeammateIdle

TaskCompleted

ConfigChange

WorktreeCreate

WorktreeRemove

SessionEnd

Three Hook Action Types

Hook Definition Structure

ECC Built-In Hooks

PreToolUse Hooks

PostToolUse Hooks

Lifecycle Hooks

Installing Hooks

Runtime Hook Controls

Writing a Custom Hook

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Using ECC

Security

Documentation Index

​How Hooks Work

​Supported Hook Events

SessionStart

UserPromptSubmit

PreToolUse

PermissionRequest

PostToolUse

PostToolUseFailure

Notification

SubagentStart

Stop

SubagentStop

PreCompact

InstructionsLoaded

TeammateIdle

TaskCompleted

ConfigChange

WorktreeCreate

WorktreeRemove

SessionEnd

​Three Hook Action Types

​Hook Definition Structure

​ECC Built-In Hooks

​PreToolUse Hooks

​PostToolUse Hooks

​Lifecycle Hooks

​Installing Hooks

​Runtime Hook Controls

​Writing a Custom Hook

Build docs developers (and LLMs) love

How Hooks Work

Supported Hook Events

Three Hook Action Types

Hook Definition Structure

ECC Built-In Hooks

PreToolUse Hooks

PostToolUse Hooks

Lifecycle Hooks

Installing Hooks

Runtime Hook Controls

Writing a Custom Hook