Hooks

​

Overview

​

When to Use

• You want to automate agent activation on specific events
• You need lint checks or tests to run before commits
• You want auto-diagnosis when CI/CD fails
• You need context loading at session start
• You want to trigger agents on file saves, merges, or releases

​

How It Works

​

Available Events

​

Available Agents

• lint-fixer — Automatic lint error resolution
• test-writer — Test generation for new or changed code
• reviewer — Code review and quality checks
• security-auditor — Security vulnerability scanning
• ci-watcher — CI/CD pipeline monitoring and diagnosis
• a11y-auditor — Accessibility compliance checks
• perf-profiler — Performance analysis and optimization
• dependency-auditor — Dependency security and update checks
• docs-writer — Documentation generation and updates

​

Hook Definition Format

---
id: {event}-{agent}
type: hook
event: {selected-event}
agent: {selected-agent}
description: {description}
globs: {comma-separated glob patterns, if any}
branches: {comma-separated branch patterns, if any}
priority: 50          # 1-100, lower runs first (optional)
timeout: 30           # seconds (optional)
---
# Hook: {event} → {agent}

{Description of what this hook does and when it activates.}

## Activation

- **Event:** {event}
- **Agent:** {agent}
- **Conditions:** {glob patterns, branch patterns, or "always"}

## Tool-Specific Behavior

- **Claude Code:** For session-start → SessionStart. Other events may use no-op or alternative strategy.
- **Cursor:** Maps to glob-based rule activation in `.cursor/rules/`
- **Others:** Hook definition stored; sync when adapter support is added

​

Conditions (Optional)

• Glob patterns: Which files trigger this hook (e.g., src/**/*.ts, *.css)
• Branch patterns: Which branches (e.g., main, release/*)

​

Custom Events

• Event naming: custom:{domain}:{action} (e.g., custom:billing:subscription-change)
• Event registration: Add custom events to hatch.json under hooks.customEvents
• Event triggering: Agents trigger custom events via emit-hook custom:{name}
• Event payload: Custom events can pass structured data via JSON payload

​

Custom Event Definition in hatch.json

{
  "hooks": {
    "customEvents": [
      {
        "name": "custom:billing:subscription-change",
        "description": "Fired when a subscription plan changes",
        "payload": { "userId": "string", "oldPlan": "string", "newPlan": "string" }
      }
    ]
  }
}

​

Hook Chaining

• Chain definition: Define ordered hook chains in hatch.json under hooks.chains
• Execution order: Hooks in a chain execute sequentially; failure in any hook stops the chain
• Error handling: Chain-level error handlers can catch and handle failures
• Conditional chaining: Hooks can conditionally trigger next hook based on output (pass/fail/skip)

​

Chain Definition in hatch.json

{
  "hooks": {
    "chains": [
      {
        "id": "pre-release-pipeline",
        "description": "Full pre-release validation chain",
        "steps": [
          { "hook": "pre-release-security-auditor", "on_fail": "stop" },
          { "hook": "pre-release-test-writer", "on_fail": "stop" },
          { "hook": "pre-release-docs-writer", "on_fail": "warn" }
        ],
        "on_error": "notify"
      }
    ]
  }
}

​

Hook Execution Ordering

• Priority: Hooks have a priority field (1-100, lower runs first, default 50)
• Parallel vs Sequential: Hooks at the same priority level run in parallel; different priority levels run sequentially
• Timeout: Each hook has a configurable timeout (default 30 seconds). Timed-out hooks are reported as failures.
• Isolation: Each hook runs in its own context

​

Priority Configuration

---
id: pre-commit-lint-fixer
type: hook
event: pre-commit
agent: lint-fixer
priority: 10
timeout: 60
---

​

Execution Example

1. lint-fixer (priority 10) — runs first
2. security-auditor (priority 20) — runs second
3. test-writer (priority 50) and reviewer (priority 50) — run in parallel, third

​

Tool-Specific Behavior

​

Claude Code

• session-start → SessionStart hook
• Other events (pre-commit, post-merge, etc.) may use no-op or alternative strategy
• Note: Claude Code’s native hooks (PreToolUse, PostToolUse, SubagentStart) are tool-lifecycle events and do NOT map to git/project events

​

Cursor

• Maps to glob-based rule activation in .cursor/rules/
• Creates .mdc rule files in .cursor/rules/hatch3r-hook-*.mdc

​

Other Tools

• Hook definitions stored; sync when adapter support is added

​

Sync to Tools

• Claude Code: Hook documentation appended to managed section of CLAUDE.md
• Cursor: Glob-based .mdc rule files in .cursor/rules/hatch3r-hook-*.mdc
• Others: No-op (hook definitions stored for future adapter support)

​

Error Handling

• /.agents/hooks/ doesn’t exist: Creates it automatically
• Invalid event type: Warns and shows the valid events table
• Agent not found: Warns but allows (agent may be added later)
• Adapter doesn’t support hooks: Generates hook definition anyway, warns that sync for that tool is a no-op
• Duplicate hook ID: Warns and asks to choose a different name or overwrite

​

Guardrails

• Hook definitions are tool-agnostic — the adapters handle translation
• Never deletes hook files without explicit user confirmation
• Always validates event names against the known events list
• Hook IDs must be unique across all hook definitions
• The command creates hook DEFINITIONS only — actual hook registration happens via npx hatch3r sync
• Does not modify adapter output files directly — they are managed by the sync pipeline