hooks.json fails settings schema validation — "unknown keys" warning on every session start
Author: NerdSnipeCreated Sep 10, 2026Updated Sep 14, 2026
When starting Claude Code with the ecc plugin enabled, this warning appears:
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 44 more ignored
Cause
hooks/hooks.json (and the 2.1.0/2.2.1 cache copies) don't conform to Claude Code's hooks schema:
- Top-level
"$schema"key (line 2) isn't part of the schema. - Every hook entry under each event (
PreToolUse,PreCompact,SessionStart,PostToolUse,PostToolUseFailure,Stop,SessionEnd) includes"description"and"id"fields alongsidematcher/hooks, which aren't recognized keys.
This produces a validation warning on every session start when the plugin is enabled, even though the hooks themselves appear to run fine.
Suggested fix
Either:
- Move
description/idmetadata out of the schema-validated shape (e.g., into a comment-only sibling file or a wrapper the plugin loader strips before handing to Claude Code), or - Confirm with Claude Code whether these keys are actually supported/planned for the hooks schema, and if not, drop them from
hooks/hooks.json.
Environment
- Repo: affaan-m/everything-claude-code
- File:
hooks/hooks.json - Reproduced with plugin versions 2.1.0 and 2.2.1 (same issue in cached copies)
Source: affaan-m/ECC