#6630: feat(hooks): add agent:turn_start and agent:turn_end lifecycle events
docs
Add two new hook events that fire when the agent begins and finishes processing an inbound message:
- agent:turn_start: Fires before the agent processes a message
- agent:turn_end: Fires after the agent sends a response (in finally block)
Both events include context about the message source, sender, and a preview of the message content. This enables integrations like status dashboards to show real-time agent activity.
Example use case: A Mission Control dashboard that shows when the agent is actively working vs idle.
Implements planned events from docs/hooks.md (replaces message:sent and message:received with more precise turn-based events).
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds two new internal hook events (`agent:turn_start` and `agent:turn_end`) emitted from the inbound message dispatch path, and documents their context payload fields in `docs/hooks.md`. The intent is to provide a turn-based lifecycle signal (start/end of processing) for integrations like dashboards.
Main concern: the `turn_end` event is emitted from a `finally` block but currently hardcodes `success: true`, so failures will be reported as successes. Additionally, `turn_start` is awaited before the main dispatch, so any unexpected failure in the hook trigger path could block message processing. The docs update is helpful, but it still lists `message:sent`/`message:received` under “Future Events” despite the PR describing them as replaced by the new turn events.
<h3>Confidence Score: 3/5</h3>
- Reasonably safe to merge, but the new hook telemetry semantics are currently incorrect for error cases.
- Changes are small and localized, but `agent:turn_end` always sets `success: true`, which can mislead downstream consumers and is likely a bug for the intended API. The hook triggers are also on the critical dispatch path, so any unexpected failure there could impact message processing.
- src/auto-reply/dispatch.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#7771: Hooks: wire lifecycle events and tests
by rabsef-bicrym · 2026-02-03
82.5%
#11597: feat(hooks): implement message:received hook
by gnufoo · 2026-02-08
82.1%
#19565: feat: add agent lifecycle hook events (session, message, error)
by tag-assistant · 2026-02-17
82.0%
#10109: feat(plugins): invoke message_received and message_sent hooks
by nezovskii · 2026-02-06
81.4%
#19922: feat(hooks): add message:received and message:sent hook events
by NOVA-Openclaw · 2026-02-18
80.9%
#7580: feat: add message:received internal hook with prompt injection
by rodrigoschott · 2026-02-03
79.9%
#9677: feat: expose incomingMessage in bootstrap hook context
by speedbal · 2026-02-05
79.5%
#6103: feat(hooks): add agent:context_overflow event for context death han...
by G9Pedro · 2026-02-01
78.8%
#7545: feat(hooks): add message:received hook for pre-turn automation
by wangtian24 · 2026-02-02
78.8%
#15732: [AI-assisted] feat: emit agent:response internal hook after replies
by zontasticality · 2026-02-13
78.5%