claudelint

Appearance

agent-hooks-invalid-schema ​

Hook configuration in agents.json violates schema requirements

Error

Rule Details ​

This rule checks that hooks declared in agents.json have the correct structure and all required fields. Hook objects must include valid event names (e.g., PreToolUse, PostToolUse, SessionStart, TaskCompleted) and properly structured matchers. Validation is performed by AgentsValidator.validateFrontmatter() using the shared validateSettingsHooks() utility. Invalid hook schemas cause runtime failures when the agent framework attempts to register event handlers.

Incorrect ​

Hook with missing required command field

json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash" }
    ]
  }
}

Hook with invalid event name

json
{
  "hooks": {
    "OnStart": [
      { "matcher": ".*", "command": "echo hi" }
    ]
  }
}

Correct ​

Properly structured hook with all required fields

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

How To Fix ​

Ensure each hook entry has a valid event name key (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, TeammateIdle, or TaskCompleted) and that each matcher object includes the required fields.

Options ​

This rule does not have any configuration options.

Resources ​

Version ​

Available since: v0.2.0