#12582: feat(hooks): emit gateway shutdown lifecycle events
docs
gateway
stale
Cluster:
Hook and Gateway Improvements
## Why
Gateway shutdown/restart is an operationally sensitive boundary where lifecycle observability is important for uptime tooling. This PR emits explicit shutdown lifecycle events so monitoring and guardrail hooks can react consistently.
## Detailed Changes
- Added internal gateway lifecycle events in close flow:
- `gateway:shutdown`
- `gateway:pre-restart` (when restart is expected)
- Hook execution is best-effort and does not block shutdown path
- Added focused tests covering gateway lifecycle event emission
## Related Links and Issues
- Existing source PR (split from): #9761
- Closes #6711
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds two new internal hook emissions to the gateway shutdown flow (`gateway:shutdown` and conditional `gateway:pre-restart`) and updates the hooks documentation accordingly. It also introduces a focused unit test that mocks internal hook dispatch and asserts the emitted event contexts during a restart-oriented shutdown.
The changes plug into the existing internal hook registry (`src/hooks/internal-hooks.ts`) by constructing `InternalHookEvent`s and calling `triggerInternalHook(...)` early in `createGatewayCloseHandler`, before the rest of the shutdown teardown proceeds.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- The change is narrowly scoped to emitting new internal hook events and updating docs/tests. The previously-raised issues (sessionKey misuse, shutdown hook await semantics, timer cleanup, docs wording) are already addressed in the current head SHA, and no new definite correctness regressions were identified in the modified code paths.
- No files require special attention
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#10679: fix(hooks): invoke gateway_start and gateway_stop in lifecycle
by yassinebkr · 2026-02-06
81.2%
#20541: fix(hooks): clear internal hooks before plugins register
by ramarnat · 2026-02-19
76.1%
#15571: feat: infrastructure foundation — hooks, model failover, sessions, ...
by tangcruz · 2026-02-13
74.3%
#23410: Gateway: require prefixes for hook request session-key overrides
by bmendonca3 · 2026-02-22
74.2%
#8121: fix(gateway): remove query parameter token support for hooks
by yubrew · 2026-02-03
74.1%
#12584: feat(hooks): wire outbound message lifecycle hooks
by vincentkoc · 2026-02-09
73.5%
#3699: fix(gateway): add error handling for tailscaleCleanup in shutdown
by Episkey-G · 2026-01-29
73.1%
#9782: feat(hooks): implement session:start and session:end lifecycle events
by kentaro · 2026-02-05
72.9%
#7128: feat: add gateway.restart RPC for graceful in-process restart
by AkashaBot · 2026-02-02
72.0%
#23763: Hooks: require session key prefixes for request override
by bmendonca3 · 2026-02-22
71.9%