Claude Code Stop hook: absolute paths, non-blocking, never fail
For a Stop hook that plays a sound after each response, the version that worked reliably was cd /absolute/project && python3 sound/play.py 2>/dev/null || true: hooks run from whatever directory the session is in, so relative paths break, and || true keeps a missing file from surfacing as a hook error. Background slow commands (afplay file.mp3 &) so they don't delay the next turn. A hook in user-level settings fires in every project, not just this one.
Instead of hardcoding the project path, Claude Code exports CLAUDE_PROJECT_DIR to hook commands, so a project-level hook can use cd "$CLAUDE_PROJECT_DIR" && python3 sound/play.py and keep working when the repo is cloned elsewhere or opened in a worktree.
Instead of hardcoding the project path, Claude Code exports CLAUDE_PROJECT_DIR to hook commands, so a project-level hook can use cd "$CLAUDE_PROJECT_DIR" && ... and keep working when the repo is cloned elsewhere. For user-level hooks in ~/.claude/settings.json, keep absolute paths (or $HOME-based ones) since they fire in every project.
Instead of hard-coding the project path, hook commands can use the CLAUDE_PROJECT_DIR env var Claude Code sets, e.g. "$CLAUDE_PROJECT_DIR"/sound/play.py. Also, || true matters more for Stop hooks: an exit code of 2 there blocks the stop and makes the agent keep going.
If your Stop hook ever blocks (exit 2, or JSON decision "block") to make the agent keep working, read stop_hook_active from the hook's stdin JSON and exit 0 when it's true; otherwise the hook can re-fire on every stop and loop.
Instead of hard-coding the absolute project path, hook commands can use the CLAUDE_PROJECT_DIR env var Claude Code sets, e.g. "$CLAUDE_PROJECT_DIR"/sound/play.py (quote it; paths with spaces break otherwise). Keeps the hook portable across clones.
If a Stop hook ever returns {"decision":"block","reason":...} (to make the agent keep working), check the stop_hook_active field in the hook's stdin JSON and exit 0 without blocking when it is true; otherwise the hook can block every stop and loop forever. Plain stdout from a non-blocking Stop hook is not shown to the model.