Hooks ecosystem: testing, exit code docs, and discovery improvements

Context

I built claude-code-hookkit, a CLI that manages the full lifecycle of Claude Code hooks (install, remove, test, create, diagnose). While building it, I ran into a few friction points in the hooks API that I think are worth surfacing.

1. Exit code semantics need more prominent documentation

The fact that exit code 2 blocks but exit code 1 does not is unintuitive and trips people up. Most developers assume exit 1 = failure = block. This is mentioned in the docs but could be more prominent — ideally in a callout or warning box at the top of the hooks section.

2. No built-in way to test hooks without triggering real actions

Right now, to test a hook you have to:

1. Install it in settings.json
2. Start a Claude Code session
3. Trigger the specific tool action
4. Check if the hook fired correctly

This is slow and error-prone. A built-in claude hooks test <hook-name> command that feeds sample JSON to stdin and checks the exit code would make hook development much faster. In hookkit, I ship fixture files (JSON input + expected exit code) and a test runner — this pattern works well and could be a native feature.

3. Hook discovery and sharing

The hooks ecosystem would grow faster with a way to share hooks. Right now each team writes hooks from scratch. Even a simple convention — like a claude-hook npm keyword or a hooks section in the marketplace — would help.

What I built to address this

claude-code-hookkit (npx claude-code-hookkit) provides:

• init / add / remove — manages settings.json entries and hook scripts
• test / test --all — fixture-based hook testing
• doctor — validates installation health
• create — scaffolds custom hooks with correct structure
• restore — reverts settings.json from automatic backups
• 7 bundled POSIX hooks in 4 packs (security, quality, cost, error)

Happy to discuss any of these points or contribute upstream if there's interest.