PreCommit and SessionStart are not valid hook events but aren't documented as invalid
Problem
The settings.json hook system currently only supports PreToolUse, PostToolUse, Notification, Stop, and SubagentStop as hook events. However, PreCommit and SessionStart — which are intuitive lifecycle events — are silently rejected with a generic schema error rather than a clear "unknown hook event" message.
The error output says:
├ PreCommit: Invalid key in record
└ SessionStart
└ 0
└ hooks: Expected array, but received undefined
SessionStart is particularly confusing: it's rejected not because the event name is invalid, but because the validator still tries to parse the hook body and fails on the missing hooks array wrapper — masking the real issue (unsupported event type).
Suggested improvements
-
Validate hook event names first — before checking the shape of the hook body, reject unknown keys with a clear message like: "SessionStart" is not a valid hook event. Valid events: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
-
Consider adding SessionStart and PreCommit as hook events — both are common workflow needs:
SessionStart: run setup commands (check tool versions, load context, display status)PreCommit: run checks before Claude Code creates a git commit (lint, detect-changes, etc.)
Environment
- Claude Code (latest as of 2026-04-07)
- macOS,
~/.claude/settings.json
PreCommitandSessionStartare not valid hook events but aren't documented as invalidProblem
The
settings.jsonhook system currently only supportsPreToolUse,PostToolUse,Notification,Stop, andSubagentStopas hook events. However,PreCommitandSessionStart— which are intuitive lifecycle events — are silently rejected with a generic schema error rather than a clear "unknown hook event" message.The error output says:
SessionStartis particularly confusing: it's rejected not because the event name is invalid, but because the validator still tries to parse the hook body and fails on the missinghooksarray wrapper — masking the real issue (unsupported event type).Suggested improvements
Validate hook event names first — before checking the shape of the hook body, reject unknown keys with a clear message like:
"SessionStart" is not a valid hook event. Valid events: PreToolUse, PostToolUse, Notification, Stop, SubagentStopConsider adding
SessionStartandPreCommitas hook events — both are common workflow needs:SessionStart: run setup commands (check tool versions, load context, display status)PreCommit: run checks before Claude Code creates a git commit (lint, detect-changes, etc.)Environment
~/.claude/settings.json