ECC/schemas/hooks.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Claude Code Hooks Configuration",
  "description": "Configuration for Claude Code hooks. Supports current Claude Code hook events and hook action types.",
  "$defs": {
    "stringArray": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1
    },
    "commandHookItem": {
      "type": "object",
      "required": [
        "type",
        "command"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "command",
          "description": "Run a local command"
        },
        "command": {
          "oneOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "$ref": "#/$defs/stringArray"
            }
          ]
        },
        "async": {
          "type": "boolean",
          "description": "Run hook asynchronously in background without blocking"
        },
        "timeout": {
          "type": "number",
          "minimum": 0,
          "description": "Timeout in seconds for async hooks"
        }
      },
      "additionalProperties": true
    },
    "httpHookItem": {
      "type": "object",
      "required": [
        "type",
        "url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "http"
        },
        "url": {
          "type": "string",
          "minLength": 1
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "allowedEnvVars": {
          "$ref": "#/$defs/stringArray"
        },
        "timeout": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": true
    },
    "promptHookItem": {
      "type": "object",
      "required": [
        "type",
        "prompt"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["prompt", "agent"]
        },
        "prompt": {
          "type": "string",
          "minLength": 1
        },
        "model": {
          "type": "string",
          "minLength": 1
        },
        "timeout": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": true
    },
    "hookItem": {
      "oneOf": [
        {
          "$ref": "#/$defs/commandHookItem"
        },
        {
          "$ref": "#/$defs/httpHookItem"
        },
        {
          "$ref": "#/$defs/promptHookItem"
        }
      ]
    },
    "matcherEntry": {
      "type": "object",
      "required": [
        "hooks"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "\\S",
          "description": "Stable identifier for a matcher entry. Required and globally unique in wrapped object format."
        },
        "matcher": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ]
        },
        "hooks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/hookItem"
          }
        },
        "description": {
          "type": "string"
        }
      }
    },
    "managedMatcherEntry": {
      "allOf": [
        { "$ref": "#/$defs/matcherEntry" },
        {
          "type": "object",
          "required": ["id"],
          "properties": {
            "hooks": { "type": "array", "minItems": 1 }
          }
        }
      ]
    },
    "managedMatcherRequiredEntry": {
      "allOf": [
        { "$ref": "#/$defs/managedMatcherEntry" },
        { "type": "object", "required": ["matcher"] }
      ]
    }
  },
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "$schema": {
          "type": "string"
        },
        "hooks": {
          "type": "object",
          "propertyNames": {
            "enum": [
              "SessionStart",
              "UserPromptSubmit",
              "PreToolUse",
              "PermissionRequest",
              "PostToolUse",
              "PostToolUseFailure",
              "Notification",
              "SubagentStart",
              "Stop",
              "SubagentStop",
              "PreCompact",
              "InstructionsLoaded",
              "TeammateIdle",
              "TaskCompleted",
              "ConfigChange",
              "WorktreeCreate",
              "WorktreeRemove",
              "SessionEnd"
            ]
          },
          "patternProperties": {
            "^(SessionStart|PreToolUse|PermissionRequest|PostToolUse|PostToolUseFailure|SubagentStart|PreCompact|InstructionsLoaded|TeammateIdle|TaskCompleted|ConfigChange|WorktreeCreate|WorktreeRemove|SessionEnd)$": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/managedMatcherRequiredEntry"
              }
            }
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/managedMatcherEntry"
            }
          }
        }
      },
      "required": [
        "hooks"
      ]
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/$defs/matcherEntry"
      }
    }
  ]
}