claudelint

Appearance

agent-hooks ​

Agent hooks must be an object with event name keys

Error

Rule Details ​

This rule enforces that the hooks field in agent markdown frontmatter is a valid object keyed by event names. The supported event names are PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, TeammateIdle, and TaskCompleted. Each key maps to an array of hook matchers. Validation is delegated to the AgentFrontmatterSchema.shape.hooks Zod schema. Correctly structured hooks allow the agent framework to register event handlers at runtime.

Incorrect ​

Hooks defined as an array instead of an object

yaml
---
name: build-agent
description: Runs build pipelines
hooks:
  - PreToolUse
  - PostToolUse
---

Hooks defined as a plain string

yaml
---
name: build-agent
description: Runs build pipelines
hooks: PreToolUse
---

Correct ​

Hooks as an object with event name keys

yaml
---
name: build-agent
description: Runs build pipelines
hooks:
  PreToolUse:
    - matcher: Bash
      command: echo "pre-check"
---

How To Fix ​

Reformat the hooks field as an object where each key is a valid event name (PreToolUse, PostToolUse, etc.) and each value is an array of hook matcher objects.

Options ​

This rule does not have any configuration options.

Resources ​

Version ​

Available since: v0.2.0