PostToolUse hook: exit code 2 does not block or undo the preceding write

Summary

When a PostToolUse hook returns exit code 2, it has no effect on the tool result — the file has already been written. This is surprising behavior that is not documented in the hooks reference.

Steps to reproduce

1. Wire a PostToolUse hook on Edit or Write events.
2. Have the hook return exit 2 with a message.
3. Observe that the edit is persisted on disk regardless.
4. Observe that agents reading the hook output may believe their edit failed and retry, causing confusion.

Expected behavior (from docs)

The hooks documentation implies exit code 2 blocks tool execution. This is true for PreToolUse but NOT for PostToolUse — the tool has already completed.

Actual behavior

• PostToolUse fires after the write completes. The file is already on disk.
• exit 2 from PostToolUse does not undo the write.
• Agents that inspect hook output may interpret it as a failure, leading to retry loops.

Proposed fix

Add a clear note in the hooks documentation for PostToolUse events:

Note: PostToolUse hooks fire after the tool has completed. Returning exit 2 will not undo the tool's action. Use PreToolUse with exit 2 to block operations before they run.

Workaround

Use PreToolUse hooks with exit 2 to block writes. Use PostToolUse hooks for informational output only (plain echo, no exit 2).

Environment

Claude Code (CLI), hooks configured in .claude/settings.json.