Claude-Code-Workflow/ccw/src/templates/hooks-config-example.json

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "description": "Example hooks configuration for CCW. Place in .claude/settings.json under 'hooks' key.",
  "hooks": {
    "session-start": [
      {
        "name": "Progressive Disclosure",
        "description": "Injects progressive disclosure index at session start with recovery detection",
        "enabled": true,
        "handler": "internal:context",
        "timeout": 5000,
        "failMode": "silent",
        "notes": [
          "Checks for recovery checkpoints and injects recovery message if found",
          "Uses RecoveryHandler.checkRecovery() for session recovery"
        ]
      }
    ],
    "session-end": [
      {
        "name": "Update Cluster Metadata",
        "description": "Updates cluster metadata after session ends",
        "enabled": true,
        "command": "ccw core-memory update-cluster --session $SESSION_ID",
        "timeout": 30000,
        "async": true,
        "failMode": "log"
      },
      {
        "name": "Mode State Cleanup",
        "description": "Deactivates all active modes for the session",
        "enabled": true,
        "command": "ccw hook session-end --stdin",
        "timeout": 5000,
        "failMode": "silent"
      }
    ],
    "Stop": [
      {
        "name": "Stop Handler",
        "description": "Handles Stop hook events with Soft Enforcement - injects continuation messages for active workflows/modes",
        "enabled": true,
        "command": "ccw hook stop --stdin",
        "timeout": 5000,
        "failMode": "silent",
        "notes": [
          "Priority order: context-limit > user-abort > active-workflow > active-mode",
          "ALWAYS returns continue: true (never blocks stops)",
          "Injects continuation message instead of blocking",
          "Deadlock prevention: context-limit stops are always allowed",
          "Uses ModeRegistryService to check active modes"
        ]
      }
    ],
    "PreCompact": [
      {
        "name": "Checkpoint Creation",
        "description": "Creates checkpoint before context compaction to preserve session state",
        "enabled": true,
        "command": "ccw hook pre-compact --stdin",
        "timeout": 10000,
        "failMode": "silent",
        "notes": [
          "Creates checkpoint with mode states, workflow state, and memory context",
          "Uses mutex to prevent concurrent compaction for same directory",
          "Returns systemMessage with checkpoint summary for context injection"
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "name": "Keyword Detection",
        "description": "Detects mode keywords in prompts and activates corresponding modes",
        "enabled": true,
        "command": "ccw hook keyword --stdin",
        "timeout": 5000,
        "failMode": "silent",
        "notes": [
          "Supported keywords: autopilot, ralph, ultrawork, swarm, pipeline, team, ultrapilot, ultraqa",
          "Maps keywords to execution modes using ModeRegistryService",
          "Injects systemMessage on mode activation"
        ]
      },
      {
        "name": "Spec Context Injection",
        "description": "Loads project specs matching prompt keywords and injects as system context",
        "enabled": true,
        "command": "ccw spec load --stdin",
        "timeout": 5000,
        "failMode": "silent"
      }
    ],
    "file-modified": [
      {
        "name": "Auto Commit Checkpoint",
        "description": "Creates git checkpoint on file modifications",
        "enabled": false,
        "command": "git add . && git commit -m \"[Auto] Checkpoint: $FILE_PATH\"",
        "timeout": 10000,
        "async": true,
        "failMode": "log"
      }
    ],
    "context-request": [
      {
        "name": "Dynamic Context",
        "description": "Provides context based on current session cluster",
        "enabled": true,
        "handler": "internal:context",
        "timeout": 5000,
        "failMode": "silent"
      }
    ]
  },
  "hookSettings": {
    "globalTimeout": 60000,
    "defaultFailMode": "silent",
    "allowAsync": true,
    "enableLogging": true
  },
  "notes": {
    "handler": "Use 'internal:context' for built-in context generation, or 'command' for external commands",
    "failMode": "Options: 'silent' (ignore errors), 'log' (log errors), 'fail' (abort on error)",
    "variables": "Available: $SESSION_ID, $FILE_PATH, $PROJECT_PATH, $CLUSTER_ID",
    "async": "Async hooks run in background and don't block the main flow",
    "Stop hook": "The Stop hook uses Soft Enforcement - it never blocks but may inject continuation messages",
    "PreCompact hook": "Creates checkpoint before compaction; uses mutex to prevent concurrent operations",
    "UserPromptSubmit hook": "Detects mode keywords and activates corresponding execution modes",
    "session-end hook": "Cleans up mode states using ModeRegistryService.deactivateMode()"
  }
}