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 valid type (command, prompt, or agent), includes the required field for its type, does not specify multiple handler fields simultaneously, and has a valid timeout value if one is provided. 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, 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