| name | safe-hooks |
| description | Use when writing, wiring, reviewing, or debugging Claude Code hooks — especially JavaScript hooks. Covers exit codes, the node-resolver wrapper, fail-open vs blocking behavior, matchers, timeouts, and security. Triggers on "write a hook", "PreToolUse/PostToolUse/Stop hook", "hook not blocking", "format on save hook". |
Safe hooks (JavaScript-first)
Hooks execute arbitrary code automatically. Treat them as a security surface.
Exit codes (the #1 footgun)
- exit 2 → blocks the action; stderr is fed back to Claude. Use for guards.
- exit 0 → success; stdout JSON (if any) is processed.
- exit 1 / other → non-blocking error; the action proceeds anyway.
A guard that uses exit 1 silently does nothing. Guards must exit 2.
Choose the right event
- PreToolUse — guards / validation (can block with exit 2).
- PostToolUse — formatting, logging (cannot undo; react only). Keep non-blocking.
- Stop / SubagentStop — wrap-up reminders. Avoid blocking.
- UserPromptSubmit — runs before every prompt with a 30s budget. Keep fast.
Hard allow/deny belongs in the permission system, not a Bash-parsing hook.
JavaScript hooks: exec-form invocation
Use exec-form — command: "node" with args — instead of a shell string. Claude
Code spawns hooks using the user's login shell, so nvm (or any other version manager)
has already placed node on PATH:
{
"PostToolUse": [
{
"matcher": "Edit|Write|MultiEdit",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/format-on-edit.mjs"],
"timeout": 60
}
]
}
]
}
Hook scripts are plain ESM .mjs — no build step, identical for .js-only and
TypeScript projects. They read the event JSON from stdin (fs.readFileSync(0))
and may print control JSON to stdout.
Rules
- Scope with
matcher (e.g. "Edit|Write") so hooks don't fire on every call.
- Quote all variables; prefer absolute paths via
${CLAUDE_PROJECT_DIR} / ${CLAUDE_PLUGIN_ROOT}.
- Fail open on infrastructure errors (missing runtime) so a broken hook never
bricks the session — unless the hook is a security guard, which should block.
- Never read or echo secrets; skip
.env and .git.
- Keep blocking hooks fast; move heavy lint/test to non-blocking or on-demand.
The plugin ships ready hooks: format-on-edit.mjs (non-blocking format),
verify-on-stop.mjs (non-blocking reminder), secret-scan.mjs (PreToolUse
guard, exit 2). Wire secret-scan under PreToolUse Edit|Write|MultiEdit.
