#9782: feat(hooks): implement session:start and session:end lifecycle events
docs
stale
size: M
## Summary
Implements the session lifecycle hooks that were previously listed as "Future Events" in the docs.
Supersedes #3804 (which was closed due to test failures).
### Changes
- **session:end**: Triggered BEFORE `/new` or `/reset` clears the session
- Context: `sessionEntry` (previous session), `sessionId`, `sessionFile`, `reason` (`"new"` or `"reset"`), etc.
- **session:start**: Triggered when a new session begins (after reset/new)
- Context: `sessionEntry`, `sessionId`, `sessionFile`, `isReset` (`true` for `/reset`, `false` for `/new`), etc.
### Event Order
For `/new` or `/reset` commands:
1. `session:end` (if previous session exists)
2. `command:new` or `command:reset`
3. `session:start` (if new session exists)
### Use Cases
- Save session context/transcripts to external memory systems on session end
- Initialize session-specific resources on session start
- Audit session lifecycle events
- Trigger cleanup or archival workflows when sessions reset
### Docs
Updated `hooks.md` to move session events from "Future Events" to a new "Session Events" section with full documentation.
### Testing
Added tests covering:
- session:end fires before command:new when previous session exists
- session:start fires with isReset context
- session:end does not fire when no previous session exists
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds two new internal hook events to the command pipeline for `/new` and `/reset`:
- Emits `session:end` before triggering `command:new|command:reset` so hooks can persist the prior session before it is cleared.
- Emits `session:start` after the command hook so hooks can initialize resources for the new session.
- Updates `docs/hooks.md` to document these new session lifecycle events and adds tests validating call order and presence/absence.
The implementation lives in `src/auto-reply/reply/commands-core.ts`, which is where command hooks are currently created and dispatched via `createInternalHookEvent(...)` / `triggerInternalHook(...)`.
<h3>Confidence Score: 4/5</h3>
- Mostly safe to merge, but the new session hook context fields are currently inaccurate for `/new` vs `/reset`.
- Change is localized and covered by tests, but `session:start` always sets `isReset: true` and `session:end` always uses `reason: "reset"`, which will mislead hook consumers and is likely to break intended behavior once hooks depend on these fields.
- src/auto-reply/reply/commands-core.ts
<!-- greptile_other_comments_section -->
<sub>(5/5) You can turn off certain types of comments like style [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#13032: feat(hooks): add unified session:before_end hook event
by TGambit65 · 2026-02-10
85.5%
#6853: fix: fire internal hooks on sessions.reset RPC (TUI/webchat /new)
by hamiltonchua · 2026-02-02
83.4%
#19565: feat: add agent lifecycle hook events (session, message, error)
by tag-assistant · 2026-02-17
82.1%
#8244: feat(hooks): add session:before_compact and session:after_compact i...
by kephail · 2026-02-03
79.3%
#3392: fix(hooks): remove debug console.log statements from session-memory...
by WinJayX · 2026-01-28
78.7%
#21155: reply: add cancellable before_reset guard for /new and /reset
by LiShengYang-yiyi · 2026-02-19
77.6%
#14243: fix: fire session-memory hook on auto-resets + topic-aware memory p...
by TheDude135 · 2026-02-11
77.6%
#13861: feat(hooks): add session:compaction hook event
by lailoo · 2026-02-11
77.5%
#8431: Hooks: add session-graphiti memory feed
by JorgeAlan · 2026-02-04
77.4%
#23763: Hooks: require session key prefixes for request override
by bmendonca3 · 2026-02-22
77.2%