#3138·ECC

hooks.json ships schema-invalid keys ($schema, description, id) → startup validation warnings

Author: kjarnot-uipsCreated Sep 16, 2026Updated Sep 16, 2026

Claude Code prints a hook validation warning at every session start:

ecc: hooks.json: unknown keys "$schema", "description" in hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], "description" in hooks.PreToolUse[1], "id" in hooks.PreToolUse[1] and 38 more ignored

Cause

hooks/hooks.json decorates entries with metadata keys that Claude Code's hook schema does not define:

  • $schema at the top level
  • description and id on every hook entry (sibling of matcher/hooks)

Claude Code validates the file, does not recognize those keys, and ignores them (hence the trailing ignored). With ~13+ hook entries × 2 keys each plus $schema, the count reaches the reported "38 more".

Impact

Cosmetic only — the keys are ignored and every hook still loads and runs. But the warning fires on every startup and looks like a config error to users.

Affected files

  • hooks/hooks.json
  • .cursor/hooks.json and scaffolds/cursor/hooks.json (same pattern, if they feed the same validator)

Suggested fix

Move the description/id metadata out of the schema-validated hooks.json (e.g. a sidecar file ecc reads for its own tooling), and drop the top-level $schema, so the file only contains keys Claude Code recognizes.

Version: ecc 2.2.0.