Feature Request: Support custom/user-defined hook event types in .claude/settings.json

Problem Statement

Framework integrations (e.g., Empirica) need to hook into Claude Code's transaction lifecycle for session assessment and enrichment (e.g., ACAT scoring post-POSTFLIGHT). Claude Code's current hook system uses hardcoded event types (PreToolUse, PostToolUse, SessionStart, etc.), which prevents registration of framework-specific custom lifecycle events.

Use Case: Empirica's transaction lifecycle (PREFLIGHT → CHECK → PRAXIC → POSTFLIGHT) needs to trigger custom assessment hooks at the POSTFLIGHT phase, but there's no way to register arbitrary event names in .claude/settings.json.

Proposed Solution

Enable .claude/settings.json to register hooks for arbitrary custom event names (in addition to the existing hardcoded events), using a namespace convention to avoid collisions.

Requirements

1. User-defined hook event names — allow .claude/settings.json to define hooks for custom event names, not just predefined ones
2. Namespace convention — recommend practice:event-name or app:event-name pattern to avoid collisions
3. Validation — optionally warn if a custom event is registered but never fired (catches misconfiguration)

Example Configuration (Post-Implementation)

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "all",
        "hooks": [{"type": "command", "command": "..."}]
      }
    ],
    "empirica:postflight": [
      {
        "matcher": "all",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/operations/bin/acat-score assess --session-id $SESSION_ID",
            "timeout": 150
          }
        ]
      }
    ]
  }
}

Benefits

• ✅ Clean architecture — frameworks' transaction lifecycles become first-class in Claude Code
• ✅ Reusable — other frameworks (cortex, etc.) can define their own custom events
• ✅ Future-proof — scales to multiple custom events without hardcoding additional event types
• ✅ Low friction — no wrapper scripts or post-hoc integration layers
• ✅ Backward compatible — existing hardcoded events continue to work unchanged

Timeline Context

This feature request is submitted to enable Empirica's async enhancement path. Empirica has a parallel fallback (wrapper script, ready for immediate deployment), so this is not blocking any critical deployment. However, if this feature is available by September 30, 2026, Empirica practices can migrate from the wrapper approach to native events.

Submitted by: Carly R. Anderson (empirica-foundation) | Date: September 10, 2026