hooks/hooks.json includes non-schema $schema/description/id fields, causing "unknown keys ... ignored" warnings on every session

[Maddogs1964]

Description

On every Claude Code session start, ECC's plugin hooks produce a warning like:

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 cause is hooks/hooks.json: it has a top-level $schema key, and every matcher entry under each event (PreToolUse, PostToolUse, Stop, etc.) carries description and id fields. Claude Code's actual hook-loading schema only recognizes matcher and hooks on a matcher entry (with type/command/async/timeout inside each hook item) — it does not accept $schema, description, or id there, so all 47 of those fields are silently dropped with a warning on every startup.

Note that scripts/ci/validate-hooks.js + schemas/hooks.schema.json don't catch this because that schema's matcherEntry definition doesn't set additionalProperties: false, so id (which isn't even declared in the schema's properties) passes CI validation even though Claude Code's real loader rejects it.

Also worth confirming: the id/description values in hooks/hooks.json don't appear to be read back by any ECC runtime code — scripts/hooks/posttooluse-dispatcher.js, for example, hardcodes its own separate list of hook ids rather than reading them from hooks.json. So these fields look like leftover/decorative metadata rather than something functionally required.

Steps to reproduce

1. Install the ECC plugin via the Claude Code plugin marketplace.
2. Start a new Claude Code session.
3. Observe the "unknown keys ... ignored" warning referencing hooks.PreToolUse[0], [1], etc.

Expected behavior

No schema warnings on startup; hooks/hooks.json should only contain keys Claude Code's hook loader recognizes (matcher, hooks, and per-hook type/command/async/timeout).

Actual behavior

Warning is printed every session, listing 47 ignored fields ($schema + description/id on each of the 21 matcher entries).

Suggested fix

Strip $schema from the top level and description/id from each matcher entry in hooks/hooks.json (and consider updating schemas/hooks.schema.json to set additionalProperties: false on matcherEntry so CI catches this class of drift in the future, if that schema is meant to mirror Claude Code's real loader).

I've validated locally that removing these 47 fields keeps the file valid JSON and eliminates the warning — happy to attach a diff/PR if useful.

Environment

• Claude Code 2.1.x
• ECC plugin version 2.2.1 (installed via marketplace)
• Windows 11

[hieuck]

same problem

[LiquidBoosts]

I also have the same issue

[pablogaray-jump]

One data point on the "these fields look decorative rather than functionally required" reading: id is load-bearing for ECC's own settings-install path, so stripping id from hooks/hooks.json (as proposed here) would break --target claude installs and CI.

Chain, measured on main at 928c1de:

• scripts/lib/install-targets/helpers.js:153-164 plans hooks/hooks.json as an update-claude-settings operation with strategy: 'merge-hook-ids'.
• That runs through materializeManagedHooks() -> validateManagedHooks() in scripts/lib/install/claude-settings.js:123-150, which throws when a matcher entry has no non-empty unique id.
• The same id is the merge/drift key for mergeManagedHooks, inspectManagedHooks, repairManagedHooks and uninstallManagedHooks (claude-settings.js:453-657), and validateRecordedManagedHooks requires it when reading recorded state back.
• scripts/ci/validate-hooks.js:157-201 independently requires id on every matcher entry (and rejects duplicates) whenever hooks.json uses the { hooks: {...} } object form. So a strip also fails CI with missing or invalid 'id' field — this is not only an additionalProperties gap in schemas/hooks.schema.json.

Calling the real installer code both ways against the shipped 2.2.1 file:

with id     -> OK
without id  -> THROW: Invalid managed hook entry at managed hooks.PreToolUse[0]: expected a non-empty unique id

(Key counts in that shipped file: 1 $schema + 24 description + 24 id = 49, which lines up with Claude Code naming 5 and summarizing "and 44 more".)

Where the leftover reading does hold: the runtime disable path never reads these fields. ECC_DISABLED_HOOKS is matched in scripts/lib/hook-flags.js:89 against the id passed as an argv token to run-with-flags.js, not against the entry's id key, so those two copies of the same id are independent today.

Net: the sidecar approach suggested in #3062 is the one that satisfies both consumers — keep the ids in a metadata file, have claude-settings.js and validate-hooks.js read them from there, and ship a hooks/hooks.json carrying only matcher + hooks. Adding additionalProperties: false to matcherEntry in schemas/hooks.schema.json is safe once the ids no longer live in that file.

Environment: ECC 2.2.1 (Claude plugin marketplace), Claude Code 2.1.267, macOS.