hooks.json fails settings schema validation — "unknown keys" warning on every session start

[NerdSnipe]

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:

1. Top-level "$schema" key (line 2) isn't part of the schema.
2. Every hook entry under each event (PreToolUse, PreCompact, SessionStart, PostToolUse, PostToolUseFailure, Stop, SessionEnd) includes "description" and "id" fields alongside matcher/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/id metadata 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)

[brennanlndz]

Hit the same warning. Two things worth adding before anyone applies the "drop them" fix,
because dropping id/description breaks ECC's own tooling.

id and description are load-bearing inside ECC. Against 2.2.1:

• scripts/lib/install-targets/helpers.js:153-165 plans the hooks install as
  sourceRelativePath: CLAUDE_HOOKS_CONFIG_PATH ('hooks/hooks.json') with
  strategy: 'merge-hook-ids' - ECC merges these entries into the user's settings.json
  addressed by entry.id.
• scripts/lib/install/claude-settings.js:149-158 and :200-208 throw
  (expected globally unique id) on a missing or duplicate id. Reconcile, verify and
  uninstall (:453, :471, :498-542, :582-657) all address entries by id.
• scripts/ci/validate-hooks.js:192 hard-errors missing or invalid 'id' field for
  exactly this file.
• scripts/lib/install/hook-consent.js:75 renders group.description in the install
  consent prompt.

So the metadata needs to move somewhere ECC can still read it - a sibling
hooks/hooks.meta.json addressed by event and index, or generating hooks/hooks.json
from a richer source at build time - rather than just being deleted.

The $schema entry may be worse than a warning. anthropics/claude-code#76451 reported
that an unknown top-level field in a plugin's hooks/hooks.json made the plugin silently
vanish from the claude.ai desktop plugin browser, with no error anywhere and the CLI
unaffected. That issue was closed by the stale bot rather than fixed, so the behaviour is
probably still live. $schema is the only top-level offender here and the one field with
no ECC consumer, so removing it is safe and may also fix desktop discoverability.

Exact count in 2.2.1 hooks/hooks.json: 1 top-level $schema + 24 id +
24 description = 49, matching the message's "5 named and 44 more". async
(7 occurrences on hook items) is not flagged, so that one is recognised.

Env: Claude Code 2.1.267, Linux, ecc 2.2.1.

[kootik]

Independent reproduction, plus one correction to the inventory that the fix will need.

Environment: Windows 10 Pro 19045, Claude Code 2.1.268, ecc 2.2.1 via superpowers-marketplace, Node v24.12.0, npm 11.4.2.

Warning text is identical to the one reported above:

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 42 more ignored

The inventory is 47, not 49

Counting 2.2.1 hooks/hooks.json directly:

where	keys	count
top level	$schema	1
each entry in hooks.*	id, description	23 × 2 = 46
		47

Entries by event: PreToolUse 8, PreCompact 1, SessionStart 2, PostToolUse 2,
PostToolUseFailure 2, Stop 7, SessionEnd 1 — 23 total, and every one carries
both id and description (no entry carries only one).

This matches the warning's own arithmetic exactly: it names 5 keys and then says
"and 42 more" → 47. The 49 above (24 + 24 + 1) appears to overcount by one entry;
worth pinning down before the metadata is moved, since the point of the exercise is that
no key gets dropped.

merge-hook-ids is observable from outside

Confirming the load-bearing-id reading above with a data point from a real installation.
On a machine where the claude-home target install had run, ~/.claude/settings.json
contains hook entries whose commands are run-with-flags.js "<hookId>" …, and 7 of those
hookIds are byte-identical to id values in the plugin's hooks/hooks.json. So the
ids in this file are read back out by something other than the harness — dropping them is
not a rename, it is a broken key.

$schema and the warning are two separable problems

Also worth folding into the fix discussion: removing $schema does not silence the
warning. The remaining 46 id/description keys still trip it on every startup, so the
desktop-plugin-browser concern in the comment above ($schema) and the startup warning
(the 46) are independent defects with independent fixes. Anyone applying the "drop
$schema" fix should not expect the warning to go away.

For completeness: the hooks themselves do keep working — the message says the keys are
ignored, and all 23 hooks still execute. So this is cosmetic plus the desktop-discoverability
question, not a functional break.

[kootik]

Precise validator rules, read out of the 2.1.268 bundle, plus a verified stopgap for anyone who wants the warning gone before the PR lands.

The validator is new in 2.1.267

grep -aoE 'hooks\.json: unknown .{0,120}' ~/.local/share/claude/versions/<ver> finds the message template in 2.1.267 and 2.1.268, and nothing in 2.1.266. So the warning arriving is a harness change, not an ECC upgrade — worth knowing when someone reports "it started yesterday" on an unchanged plugin.

What it accepts, exactly

Deobfuscated from the bundle (2.1.268):

const allowedTop   = new Set(["description", "hooks", "modules", "surface"]);
const allowedGroup = new Set(["matcher", "hooks"]);

// top level
Object.keys(file).filter(k => !allowedTop.has(k)).map(quote)      // -> `"$schema"`
// every matcher group
Object.keys(group).filter(k => !allowedGroup.has(k)).map(quote)   // -> `"id"`, `"description"`
// hooks[] entries are not inspected at all

Three consequences for the fix:

• statusMessage (PR fix(hooks): align Claude config with schema #3058) is safe. Nothing inside hooks[] is validated — type, command, timeout, async, statusMessage are all outside the check. Only the group level is strict, so moving id into a handler field introduces no new warning.
• The allowed top-level set is description | hooks | modules | surface, not just description | hooks. $schema is the only offender ECC has today, but a future top-level key has four slots to fit into, not two.
• The message is a flattened list, not grouped by location. It is [...top-level keys, ...group keys], truncated with slice(0, 5) and and N more appended — which is why it reads "$schema", "description" in hooks.PreToolUse[0] as if $schema belonged to PreToolUse[0]. It does not; the two entries just sit next to each other. That also explains the 5 + 42 = 47 arithmetic.

For completeness on visibility: the notice goes to the UI log sink (and lands in the session transcript as {"type":"system","subtype":"informational","level":"notice"}), so it is invisible in claude -p, --debug, doctor and --verbose. The only reliable check is an interactive start or a grep of the transcript.

Verified stopgap without touching the clone

The marketplace checkout must keep id (merge-hook-ids reads it back), but the plugin cache copy the harness actually loads can be patched: strip $schema at the top level and id + description from each group in ~/.claude/plugins/cache/ecc/ecc/<ver>/hooks/hooks.json, leaving every matcher / hooks[] command byte-identical.

Measured on 2.2.1 with a local replica of the validator above as the check:

	violations
before	47
after	0

claude plugin details ecc@ecc still reports the 7 hook events and all 23 handlers are unchanged. Because known_marketplaces.json carries autoUpdate: true, the patch has to be reapplied per plugin version — I wrapped it in a script plus a SessionStart hook that re-checks by file hash and stays silent unless it actually had to repair the file.

Both workarounds become unnecessary once #3058 ships; posting the mechanism mainly so the next person hitting this has the exact rule set instead of a diff to reverse-engineer.