[DOCS] Hooks reference says PreCompact cannot block compaction

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

Exit code 2 behavior per event, Decision control, and the PreCompact hook reference

Current Documentation

The hooks reference currently describes PreCompact as non-blocking:

| PreCompact | No | Shows stderr to user only | | PostCompact | No | Shows stderr to user only |

And the decision-control table says PreCompact has no structured blocking support:

| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |

The event-specific section only documents input fields:

### PreCompact Runs before Claude Code is about to run a compact operation. In addition to the common input fields, PreCompact hooks receive trigger and custom_instructions.

What's Wrong or Missing?

Changelog v2.1.105 added blocking support for PreCompact hooks:

Added PreCompact hook support: hooks can now block compaction by exiting with code 2 or returning {"decision":"block"}

But the current docs still say the opposite: that PreCompact cannot block and has no decision control. That leaves users with incorrect guidance for both manual and auto compaction hooks, and it hides the JSON shape they now need to use when they want to prevent compaction.

Suggested Improvement

Update the hooks documentation to reflect the v2.1.105 behavior change:

1. In Exit code 2 behavior per event, change PreCompact to show that exit code 2 blocks compaction.
2. In Decision control, add PreCompact to the events that support top-level decision: "block" and reason.
3. In the PreCompact section, document both blocking patterns:

• exit with code 2
• exit 0 and return {"decision":"block","reason":"..."}

1. Clarify whether the blocking behavior applies to both manual and auto triggers.
2. Add a short example so hook authors can implement this without inferring behavior from release notes.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | Explicitly says PreCompact cannot block and has no decision control |
| https://code.claude.com/docs/en/hooks-guide | Higher-level hooks guide lists PreCompact, but does not surface the new blocking capability |
| https://code.claude.com/docs/en/agent-sdk/agent-loop | Describes PreCompact only as a pre-compaction side-effect hook |
| https://code.claude.com/docs/en/agent-sdk/hooks | SDK hook reference lists PreCompact as available but does not document the new block/decision behavior |

Total scope: 4 pages affected

Source: Changelog v2.1.105

Entry: Added PreCompact hook support: hooks can now block compaction by exiting with code 2 or returning {"decision":"block"}