docs: clarify hook blocking exit code

examples/hooks/bash_command_validator_example.py

@@ -58,7 +58,7 @@ def main():
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError as e:
         print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
-        # Exit code 1 shows stderr to the user but not to Claude
+        # Exit code 1 is a non-blocking hook error; the tool call continues.
         sys.exit(1)
 
     tool_name = input_data.get("tool_name", "")
@@ -75,7 +75,7 @@ def main():
     if issues:
         for message in issues:
             print(f"• {message}", file=sys.stderr)
-        # Exit code 2 blocks tool call and shows stderr to Claude
+        # Only exit code 2 blocks the tool call and sends stderr to Claude.
         sys.exit(2)
 
 

plugins/plugin-dev/skills/hook-development/SKILL.md

@@ -297,6 +297,11 @@ Execute when Claude sends notifications. Use to react to user notifications.
 - `2` - Blocking error (stderr fed back to Claude)
 - Other - Non-blocking error
 
+**Warning:** Only exit code `2` blocks tool execution. Exit code `1` and
+all other non-zero codes are treated as non-blocking errors, so the tool call
+continues. Use `exit 2` or `sys.exit(2)` for enforcement hooks that must
+prevent an action.
+
 ## Hook Input Format
 
 All hooks receive JSON via stdin with common fields:

plugins/plugin-dev/skills/hook-development/scripts/README.md

@@ -153,6 +153,8 @@ Check:
 ### Hook fails silently
 
 - Check exit codes (should be 0 or 2)
+- Use exit code `2` for blocking enforcement; exit code `1` is non-blocking
+  and the tool call continues
 - Ensure errors go to stderr (`>&2`)
 - Validate JSON output structure