claudelint

Appearance

hooks-invalid-config ​

Hook configuration must be valid

Error

Rule Details ​

This rule validates the structure of hook definitions inside settings files. It checks that each hook handler has a recognized type, includes the required field for its type, does not specify multiple handler fields simultaneously, and has a valid timeout value if one is provided. Both prompt and agent hooks use the prompt field. Malformed hook configurations will cause runtime errors when Claude Code attempts to execute them.

Incorrect ​

Hook with invalid type

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "invalid",
        "command": "echo hello"
      }]
    }]
  }
}

Hook missing required command field

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command"
      }]
    }]
  }
}

Hook with multiple handler fields

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "echo hello",
        "prompt": "also do this"
      }]
    }]
  }
}

Correct ​

Valid command hook

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo Pre-tool check"
      }]
    }]
  }
}

Valid prompt hook with timeout

json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "Review the written file",
        "timeout": 30000
      }]
    }]
  }
}

How To Fix ​

Ensure each hook has a valid type (command, http, prompt, or agent) and includes the corresponding handler field. Remove any extra handler fields so only one is present. If a timeout is specified, ensure it is a positive number.

Options ​

This rule does not have any configuration options.

Resources ​

Version ​

Available since: v0.2.0