agent-hooks-invalid-schema

Hook configuration in agents.json violates schema requirements

pdugan20@pdugan20

GitHub

From plugin

claudelint

1113 skills13 agents1 command1 hook

Install

$ npx -y skills add pdugan20/claudelint --agent claude-code

How it fires

How this agent gets triggered: by you, by Claude, or both.

Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.

Context preview

The summary Claude sees to decide when to auto-load this agent.

Hook configuration in agents.json violates schema requirements

Agent definition

agent-hooks-invalid-schema.md

description: "Hook configuration in agents.json violates schema requirements"

agent-hooks-invalid-schema

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

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

Hook with invalid event name

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

Correct

Properly structured hook with all required fields

{
  "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.

Related Rules

[`agent-hooks`](/rules/agents/agent-hooks)
[`hooks-invalid-event`](/rules/hooks/hooks-invalid-event)

Resources

[Rule Implementation](https://github.com/pdugan20/claudelint/blob/main/src/rules/agents/agent-hooks-invalid-schema.ts)
[Rule Tests](https://github.com/pdugan20/claudelint/blob/main/tests/rules/agents/agent-hooks-invalid-schema.test.ts)