Startup warning: unknown key "description" in hooks.json (3 events)

[wxhou]

Summary

Claude Code prints a schema warning on every session start when prompt-improver v0.6.1 is installed:

prompt-improver: hooks.json: unknown keys "description" in hooks.UserPromptSubmit[0], "description" in hooks.PreToolUse[0], "description" in hooks.SubagentStart[0] ignored

Root cause

hooks/hooks.json adds a "description": "..." field to the top level of each hook event entry (alongside matcher / hooks). The Claude Code hooks schema only accepts matcher and hooks there, so the unknown key is reported and ignored.

The field is presumably intended as documentation, but the schema has no place for it — comments in that position surface as startup warnings.

Affected locations (v0.6.1)

• hooks.UserPromptSubmit[0].description
• hooks.PreToolUse[0].description
• hooks.SubagentStart[0].description

Impact

Cosmetic only — the hooks themselves load and run correctly (the engine fires on all three events). But every user sees this warning on every session start, which erodes trust / looks like a bug.

Suggested fix

Remove the three description fields from hooks/hooks.json. If inline documentation is wanted, a // comment is not valid JSON either — a README note or a description field in plugin.json (which does support it) is the schema-safe place.

Environment

• prompt-improver v0.6.1 (installed from severity1-marketplace)
• Claude Code current (warning text as of Sep 2026)
• macOS 25.6.0