writing-hooks
Writing Hooks
Scope: covers Claude Code
hooks.jsonauthoring and hook script design. Hook event vocabularies are per-tool and NOT 1:1 mappable (nlpm design decision #4): Claude usesPreToolUse/PostToolUse/Stop/etc.; Codex overlaps with Claude plusPostCompact/SubagentStart; Antigravity/Gemini uses a differentBefore*/After* Agent/Model/Tooldecomposition. The hook-script design principles here (idempotency, fail-open, exit codes, portable paths) transfer across tools; the event names and config locations do not. For the authoritative per-tool event tables see [[nlpm:conventions-claude]] §7, [[nlpm:conventions-codex]] §6, [[nlpm:conventions-antigravity]] §5. For plugin architecture, see [[writing-plugins]]. For rules (which are simpler but static), see [[writing-rules]].
1. Three Hook Types
| Type | What it does | When to use | Complexity |
|---|---|---|---|
command |
Runs a shell script, reads JSON from stdin | Deterministic checks: file existence, JSON validation, regex matching | Medium |
prompt |
Injects text into Claude's context | Advisory: reminders, context injection, style guidance | Low |
agent |
Spawns a verification agent | Complex verification: code quality, semantic analysis, multi-file checks | High |