PostToolUse hooks: exit code 2 shows 'blocking error' but doesn't actually block

Description

When a PostToolUse hook exits with code 2 and writes to stderr, the UI displays "blocking error" but the edit is not actually blocked — the file change goes through successfully.

Steps to Reproduce

1. Create a PostToolUse hook in .claude/settings.json:

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/post-edit-checks.sh",
        "timeout": 60
      }
    ]
  }
]

1. Create a hook script that exits with code 2:

#!/bin/bash
echo "Some warning message" >&2
exit 2

1. Make an edit to a file

Expected Behavior

Either:

• The terminology should be different (e.g., "hook warning" instead of "blocking error") since PostToolUse can't actually block an edit that already happened
• Or the documentation should clarify that "blocking" for PostToolUse means something different than for PreToolUse

Actual Behavior

• UI shows: PostToolUse:Edit hook blocking error
• But the edit succeeds and the file is modified
• Claude (the AI) can see the stderr output, which is useful

Analysis

This makes sense technically — PostToolUse runs after the tool has executed, so it can't undo/block the edit. The "blocking" terminology is misleading since:

1. For PreToolUse: exit code 2 can actually prevent the tool from running
2. For PostToolUse: exit code 2 can't undo what already happened, it just surfaces output to Claude

Suggestion

Consider renaming the message for PostToolUse hooks to something like:

• "PostToolUse:Edit hook reported error"
• "PostToolUse:Edit hook warning"

Or document this distinction clearly in the hooks documentation.

Environment

• Claude Code CLI
• macOS