#16788: feat(hooks): emit compaction lifecycle hooks
docs
agents
size: L
Cluster:
Compaction Hooks Enhancement
## Why
Compaction is a critical lifecycle boundary for observability and guardrails, but runtime hook visibility was incomplete. This PR adds explicit compaction lifecycle emissions so operators and plugins can reliably track pre/post compaction state. lobster-biscuit
## Split Context
This PR was split from closed umbrella PR #9761: https://github.com/openclaw/openclaw/pull/9761.
## Detailed Changes
- Internal hook emissions added in compaction flow:
- `session:compact:before`
- `session:compact:after`
- Plugin hook wiring added in compaction flow:
- `before_compaction`
- `after_compaction`
- Hook metadata now includes counts/token-oriented context (without full message snapshots)
- Added focused test coverage for compaction hook emission and payload shape
## Related Links, Issues and Resolutions
- Closed source PR: #9761
- Related issues:
- Closes #7175
- Closes #9611
- #7420
- Closes #9527
- Closes #11617
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds internal (`session:compact:before`, `session:compact:after`) and plugin (`before_compaction`, `after_compaction`) hook emissions to the compaction flow with count/token metadata. The implementation correctly passes context including `sessionId`, `agentId`, `sessionKey`, `workspaceDir`, and `messageProvider` to plugin hooks, addressing previous concerns about missing `sessionId`. The PR also includes a subtle bug fix changing `cwd: resolvedWorkspace` to `cwd: effectiveWorkspace` to properly respect sandbox settings.
- Internal hooks emit structured events with message counts and token estimates before/after compaction
- Plugin hooks receive metadata without full message snapshots (by design per TODOs #7175, #9611)
- Test coverage validates hook emission, payload structure, and edge cases (empty transcripts, missing sessionKey)
- `compactedCount` correctly measures total reduction from validated transcript through both history limiting and compaction
- Previous thread concerns about missing `sessionId` in plugin context have been resolved
<h3>Confidence Score: 4/5</h3>
- Safe to merge with high confidence - well-tested hook implementation with proper error handling
- The implementation is solid with comprehensive test coverage and proper error handling. Previous concerns about missing `sessionId` have been addressed. The change from `resolvedWorkspace` to `effectiveWorkspace` is a legitimate bug fix. Hook payloads intentionally omit full message snapshots per design decisions documented in TODOs. Loses one point only due to the documentation formatting issue already flagged in previous threads (missing blank line before heading).
- No files require special attention - all changes are well-structured and tested
<sub>Last reviewed commit: 85d9ced</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#3749: fix(plugins): invoke before_compaction and after_compaction hooks d...
by taronsung · 2026-01-29
84.5%
#8244: feat(hooks): add session:before_compact and session:after_compact i...
by kephail · 2026-02-03
83.8%
#16915: fix: await compaction hooks with timeout to prevent cross-session d...
by maximalmargin · 2026-02-15
83.3%
#13861: feat(hooks): add session:compaction hook event
by lailoo · 2026-02-11
82.4%
#20184: feat: memory plugin compaction control
by solstead · 2026-02-18
80.6%
#18889: feat(hooks): add agent and tool lifecycle boundaries
by vincentkoc · 2026-02-17
75.9%
#13032: feat(hooks): add unified session:before_end hook event
by TGambit65 · 2026-02-10
75.7%
#11153: refactor(hooks): replace console.warn/error with subsystem logger
by hclsys · 2026-02-07
75.2%
#23019: fix(hooks): use globalThis singleton for internal hooks handlers Map
by karmafeast · 2026-02-21
75.1%
#9914: fix(hooks): resolve bundled hook dist paths and packaging checks
by zimmra · 2026-02-05
75.0%