fix(hooks): restore precompact save nudge with opt-in two-phase block (refs #858)

[junbuluv]

Summary

Follow-up to #858 / #885. Issue #858 reported that the precompact hook hard-blocked /compact with no escape. PR #885 fixed the symptom by always returning {} — but dropped the save nudge entirely, so the model now gets no signal that compaction is imminent. This PR restores the nudge without re-introducing the original footgun.

What changed

• Default (warn-only, issue PreCompact hook always blocks /compact — no way to acknowledge/bypass #858 Option 3): the hook prints the nudge to stderr (Claude Code surfaces hook stderr to the model) and returns {}. Compaction still proceeds; the model just sees the nudge first. Strict superset of the post-fix: replace invalid 'decision: allow' with {} in hooks (closes #872) #885 behavior.
• Opt-in (MEMPAL_BLOCK_COMPACT=1, issue PreCompact hook always blocks /compact — no way to acknowledge/bypass #858 Option 2): two-phase hard-block. First /compact this session blocks with the nudge as the reason; the next attempt clears a per-session flag at \$STATE_DIR/\${SESSION_ID}_blocked_compact and lets compaction proceed. Gives users a forced save-before-compact pause without re-creating the PreCompact hook always blocks /compact — no way to acknowledge/bypass #858 footgun (the original block had no escape).
• Stale header comments at lines 11–12 and 40–41 (which still claimed the hook "ALWAYS blocks") are updated to describe the actual behavior.

Mirrors the MEMPAL_VERBOSE opt-in pattern already used by mempal_save_hook.sh.

Why not just leave it as echo '{}'

The hook header in mempal_precompact_hook.sh describes its purpose as a safety net — "forces one final save of EVERYTHING before [compaction]". After #885, there's no save signal at all: the hook does its background mempalace mine (only if MEMPAL_DIR is set, which is empty by default) and exits silent. The model never learns compaction is about to happen.

Restoring a model-visible nudge re-establishes the documented purpose; routing it through stderr (rather than a decision: block) keeps /compact non-blocking for the default case.

Test plan

• bash -n hooks/mempal_precompact_hook.sh — syntax OK
• Default mode: stdin {\"session_id\":\"X\"} → stdout {}, stderr contains nudge, exit 0
• MEMPAL_BLOCK_COMPACT=1 first call: stdout {\"decision\":\"block\",\"reason\":\"…\"}, flag file created
• MEMPAL_BLOCK_COMPACT=1 second call: stdout {}, flag file removed
• Verify in a real Claude Code session that stderr nudge surfaces to the model

Refs

• PreCompact hook always blocks /compact — no way to acknowledge/bypass #858 (original bug — closed but the underlying safety nudge is gone post-fix)
• fix: replace invalid 'decision: allow' with {} in hooks (closes #872) #885 (the previous fix that over-corrected)

[mvalentsev]

Heads up: this PR targets main, but the project's default branch is develop -- which is where the recent precompact-hook history landed. Of the 77 commits in the diff, 76 are from develop already (igorls, jphein, milla-jovovich, etc.) and only 6160f68e ("fix(hooks): restore precompact save nudge with two-phase opt-in block") is yours. Re-targeting to develop (and rebasing the branch onto its tip) would shrink the diff to your single hooks/mempal_precompact_hook.sh change.

One framing nit on the PR description: #885 was a different fix (replacing the invalid decision: "allow" with {} per Claude Code hooks API, closing #872). The precompact-block fix this PR is following up on is #863 (merged 2026-04-15).