feat(hooks): add lifecycle events for sessions and agent turns by mverrilli · Pull Request #6885 · openclaw/openclaw

mverrilli · 2026-02-02T04:55:10Z

Summary

Adds comprehensive session lifecycle and agent execution hooks, enabling event-driven automation for session transitions, agent turns, memory management, and session maintenance operations.

Hooks Added

Session Lifecycle Events

session:start - Fires when a new persisted session begins (user-initiated /new//reset, or auto-recovery)
session:end - Fires when a persisted session terminates (all transition types: user commands, idle timeout, daily reset, auto-recovery)
session:reset - Fires after session:end during resets, providing transition context (old/new session IDs and entries)

Session Maintenance Events

session:compaction - Fires after session history compaction completes (inline or during memory flush)

Agent Execution Events

agent:reply - Fires after each agent turn completes with user input and/or assistant output
agent:flush - Fires when memory flush starts (context approaching token limit)
agent:bootstrap - Fires before workspace bootstrap files are injected (hooks can mutate bootstrap files)

Key Features

Complete Session Coverage

All transition types: user resets (/new, /reset), idle timeout, daily reset, and auto-recovery (compaction failure, role-ordering conflicts)
Correct execution order: Commands execute on the old session before transition occurs
Session guards: All session/agent hooks require valid sessionKey to prevent empty-key emissions

Rich Event Context

session:end and session:reset provide:

Full session entries (old and new)
Reset reason enum: user_command, idle_timeout, daily_reset, compaction_failure, role_ordering_conflict
Reason-specific metadata (idle duration, daily reset timestamps, failure details)

agent:reply provides:

User input and assistant output
Session ID, turn ID, sender ID

agent:flush provides:

Session ID
Context token count
Flush phase and reason

session:compaction provides:

Session ID
Trigger type (auto_compaction or memory_flush)
Updated compaction count
Pre-compaction token count

Hook Message System

Prepending: Hooks can push messages to event.messages array; messages are prepended to agent responses
Best-effort delivery: Messages sent when routing context is available
Command hooks always fire: command:* events emit regardless of persistence, but message delivery depends on routing context

Lifecycle Patterns

User-initiated reset (/new or /reset):

command:new or command:reset fires immediately
session:end → session:reset (if replacing existing session)
session:start fires during agent turn

Auto-recovery reset (compaction failure/role conflicts):

session:end → session:reset fire during reset
session:start fires when agent turn runs

Idle timeout / Daily reset:

session:end → session:reset fire on expiration
session:start fires during next agent turn

Bug Fixes

Session entry preservation: Fixed memory flush no-flush paths to preserve session entries
Hook reliability: Improved message ordering and delivery consistency
Execution order: Fixed hook firing order (commands now execute on correct session before transitions)

Documentation

Comprehensive documentation in docs/hooks.md covering:

All event types with detailed context schemas
Lifecycle patterns for each scenario (user resets, timeouts, auto-recovery)
Hook creation guide with examples
Message delivery semantics
Event ordering guarantees

Testing

Verified event sequences for all session transitions:

User-initiated resets (/new, /reset)
Idle timeout expiration
Daily reset triggers
Auto-recovery scenarios (compaction failures, role conflicts)
Memory flush operations
Session compaction (inline and during flush)

Use Cases

Session snapshots: Save session context before resets
Audit trails: Log all commands, turns, and session transitions
External automation: Trigger workflows on session/agent events
Bootstrap customization: Inject dynamic content during agent startup
Memory monitoring: Track flush patterns and compaction frequency
Compliance: Record all agent interactions with full context

Changes: 883 additions, 77 deletions across 10 files
Main files: agent-runner.ts (383+), commands-session.ts (78+), session.ts (81+), get-reply.ts (78+), hooks.md (81+)

This was AI assisted. I understand what the code does.
Tested locally with comprehensive event verification.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5cecd487d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/auto-reply/reply/agent-runner.ts

greptile-apps

_{2 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

docs/automation/hooks.md

src/auto-reply/reply/agent-runner.ts

chatgpt-codex-connector

💡 Codex Review

https://github.com/openclaw/openclaw/blob/1a44949f241e347280f5e90dab11e721ea0b570e/src/auto-reply/reply/agent-runner.ts#L352-L354
Emit lifecycle hooks even on final run outcomes

The early return for runOutcome.kind === "final" skips the new session:start and agent:reply hook emissions that happen later in this function. This matters in the reset/error paths where runAgentTurnWithFallback returns kind: "final" after resetting the session (e.g., compaction failure, role ordering conflict), so hooks never observe the session start or the warning reply that is actually sent. If hooks are meant to track all session starts and replies, consider emitting them before returning in this branch or handling the final outcome alongside the normal response flow.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

mverrilli · 2026-02-03T13:41:49Z

Re: Emit lifecycle hooks even on final run outcomes

Fixed this and similar edge cases. Also ran across a small bug that returned max tokens instead of actual tokens which is now fixed.

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b24b09ae80

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/auto-reply/reply/agent-runner.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d58c0f210

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/auto-reply/reply/agent-runner.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 503c092c7c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/auto-reply/reply/agent-runner.ts

chatgpt-codex-connector · 2026-02-03T17:33:40Z

Codex Review: Didn't find any major issues. Nice work!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

greptile-apps

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

src/auto-reply/reply/session.ts

docs/hooks.md

greptile-apps

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

src/auto-reply/reply/agent-runner-memory.ts

docs/hooks.md

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

greptile-apps · 2026-02-03T18:43:39Z

Additional Comments (1)

src/auto-reply/reply/commands-session.ts
This can emit a command:stop hook with an empty sessionKey via abortTarget.key ?? params.sessionKey ?? "". If both are unset for a given command source, hook handlers that route/index by sessionKey won’t be able to associate the event.

Consider skipping hook emission when there’s no session key, or ensuring a stable fallback key is always available.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/auto-reply/reply/commands-session.ts
Line: 328:333

Comment:
This can emit a `command:stop` hook with an empty `sessionKey` via `abortTarget.key ?? params.sessionKey ?? ""`. If both are unset for a given command source, hook handlers that route/index by `sessionKey` won’t be able to associate the event.

Consider skipping hook emission when there’s no session key, or ensuring a stable fallback key is always available.

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

mverrilli · 2026-02-05T00:10:21Z

@greptileai review

greptile-apps

_{2 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner-execution.ts

src/auto-reply/reply/agent-runner.ts

greptile-apps · 2026-02-05T00:13:58Z

Additional Comments (1)

src/auto-reply/reply/agent-runner.ts
Wrong session file resolver

resetSession() builds nextSessionFile using resolveSessionTranscriptPath(nextSessionId, agentId, sessionCtx.MessageThreadId) (agent-runner.ts:311-315), but elsewhere the code treats sessionFile as the session JSONL path resolved via resolveSessionFilePath(...) (and uses resolveSessionTranscriptPath(...) for transcript/derived paths). Storing a transcript path into SessionEntry.sessionFile can break later reads/writes that expect the JSONL session file (e.g., compaction/memory tooling that opens the session file). This should use the same resolver used in initSessionState when setting sessionEntry.sessionFile.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/auto-reply/reply/agent-runner.ts
Line: 311:315

Comment:
**Wrong session file resolver**

`resetSession()` builds `nextSessionFile` using `resolveSessionTranscriptPath(nextSessionId, agentId, sessionCtx.MessageThreadId)` (`agent-runner.ts:311-315`), but elsewhere the code treats `sessionFile` as the session JSONL path resolved via `resolveSessionFilePath(...)` (and uses `resolveSessionTranscriptPath(...)` for transcript/derived paths). Storing a transcript path into `SessionEntry.sessionFile` can break later reads/writes that expect the JSONL session file (e.g., compaction/memory tooling that opens the session file). This should use the same resolver used in `initSessionState` when setting `sessionEntry.sessionFile`.

How can I resolve this? If you propose a fix, please make it concise.

mverrilli · 2026-02-05T00:15:35Z

@greptileai The current implementation is correct and matches initSessionState.

Evidence from session.ts:331-335:
if (!sessionEntry.sessionFile) {
sessionEntry.sessionFile = resolveSessionTranscriptPath(
sessionEntry.sessionId,
agentId,
ctx.MessageThreadId,
);
}

Both use the same pattern:

initSessionState (session.ts:331): Uses resolveSessionTranscriptPath to SET sessionFile
resetSession (agent-runner.ts:311): Uses resolveSessionTranscriptPath to SET sessionFile

The distinction:

resolveSessionTranscriptPath: Generates the path for a NEW session (used when SETTING)
resolveSessionFilePath: Reads the path from an EXISTING entry (used when READING)

The current code correctly uses resolveSessionTranscriptPath when creating a new session file path, consistent with how sessions are initialized throughout the codebase.

greptile-apps · 2026-02-05T00:16:10Z

You're correct. After reviewing session.ts:331-335, the implementation is indeed consistent with initSessionState. Both use resolveSessionTranscriptPath when initializing or resetting a session to set the sessionFile field.

The naming is a bit confusing (sessionFile stores the transcript path), but the pattern is applied consistently throughout the codebase. My earlier concern was misplaced.

mverrilli · 2026-02-05T00:22:32Z

@greptileai review

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/agent-runner.ts

src/auto-reply/reply/agent-runner-memory.ts

vincentkoc · 2026-02-05T01:53:36Z

@mverrilli do you need a hand with this? I need this PR for a few things im working through atm.

mverrilli · 2026-02-05T05:11:33Z

@mverrilli do you need a hand with this? I need this PR for a few things im working through atm.

Hey @vincentkoc I did some refactoring and have just been plugging away at edge cases and minor inconsistencies throughout the day although I let the code reviewer take me astray for a bit. You can test what I have checked in right now. I just fixed the ordering and alignment of events. Event hooks are on a "best effort" basis as implemented here. Let me know if you have any trouble.

vincentkoc · 2026-02-05T22:11:59Z

@mverrilli i decided to take a more comprehensive approach as there are more deep routed issues with just adding the events to ensure full coverage, i decided to add changes in my own PR #9761

mverrilli · 2026-02-05T22:41:11Z

@vincentkoc alright, yeah.. I was avoiding some of the bigger issues I noticed as I was trying to keep the PR focused on what I needed for my hooks. I did add compactions events today and typed them. was thinking to add the end phase as well.

vincentkoc · 2026-02-05T22:45:04Z

@vincentkoc alright, yeah.. I was avoiding some of the bigger issues I noticed as I was trying to keep the PR focused on what I needed for my hooks. I did add compactions events today and typed them. was thinking to add the end phase as well.

Do you have a PR link open/closed for the compaction?

mverrilli · 2026-02-05T23:02:12Z

@vincentkoc 009d561 That's the commit, I hadn't made a PR specifically for it, I just added it to this one.

Add internal hook events for session and agent lifecycle transitions: - session:start — fires when a new session begins (user-initiated or auto-recovery) - session:end — fires when a session ends (reset, idle timeout, daily rollover) - session:reset — fires on session transitions with old/new session context - session:compaction — fires after auto-compaction or memory flush compaction - agent:reply — fires after each agent turn with input/output/turnId - agent:flush — fires before memory flush runs - command:stop — fires when /stop is issued with persistence status Shared helpers extracted to hook-helpers.ts to deduplicate emission logic across agent-runner, followup-runner, get-reply, and command handlers. Session reset reason tracking added to session.ts for hook context. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Add documentation for all new internal hook events including event names, trigger conditions, context payloads, and delivery semantics. Co-Authored-By: Claude Opus 4.6 <[email protected]>

mverrilli · 2026-02-13T02:02:53Z

Abandoning as there are many hook PRs now along with some just merged that overlaps with this.

openclaw-barnacle bot added the docs Improvements or additions to documentation label Feb 2, 2026

chatgpt-codex-connector bot reviewed Feb 2, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

greptile-apps bot reviewed Feb 2, 2026

View reviewed changes

mverrilli force-pushed the session_events branch 2 times, most recently from 17b3219 to 1a44949 Compare February 3, 2026 11:45

chatgpt-codex-connector bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

greptile-apps bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/session.ts Outdated Show resolved Hide resolved

docs/hooks.md Outdated Show resolved Hide resolved

greptile-apps bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/agent-runner-memory.ts Outdated Show resolved Hide resolved

docs/hooks.md Outdated Show resolved Hide resolved

greptile-apps bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

greptile-apps bot reviewed Feb 3, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

mverrilli force-pushed the session_events branch from 007d341 to e9de691 Compare February 3, 2026 19:20

mverrilli force-pushed the session_events branch from dea9539 to baa83d4 Compare February 5, 2026 00:09

greptile-apps bot reviewed Feb 5, 2026

View reviewed changes

src/auto-reply/reply/agent-runner-execution.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/agent-runner.ts Outdated Show resolved Hide resolved

mverrilli force-pushed the session_events branch from baa83d4 to 9ff7083 Compare February 5, 2026 00:21

greptile-apps bot reviewed Feb 5, 2026

View reviewed changes

src/auto-reply/reply/agent-runner.ts Show resolved Hide resolved

src/auto-reply/reply/agent-runner-memory.ts Show resolved Hide resolved

mverrilli force-pushed the session_events branch 2 times, most recently from a9b16ff to 167ee17 Compare February 5, 2026 05:08

vincentkoc mentioned this pull request Feb 5, 2026

feat(hooks): fixed and adding various agent, messaging, system and compaction hooks #9761

Closed

mverrilli mentioned this pull request Feb 6, 2026

Feature: session:end internal hook event #10142

Open

mverrilli force-pushed the session_events branch from 009d561 to 10c161d Compare February 8, 2026 19:52

vincentkoc mentioned this pull request Feb 9, 2026

feat(hooks): add agent and tool lifecycle boundaries #12583

Closed

mverrilli force-pushed the session_events branch from 10c161d to cdbbee3 Compare February 12, 2026 21:18

openclaw-barnacle bot added the size: L label Feb 12, 2026

mverrilli and others added 2 commits February 12, 2026 23:26

docs(hooks): document session lifecycle and agent execution events

a83cebe

Add documentation for all new internal hook events including event names, trigger conditions, context payloads, and delivery semantics. Co-Authored-By: Claude Opus 4.6 <[email protected]>

mverrilli force-pushed the session_events branch from cdbbee3 to a83cebe Compare February 12, 2026 23:43

mverrilli closed this Feb 13, 2026

This was referenced Feb 17, 2026

feat(hooks): add agent and tool lifecycle boundaries #18885

Closed

feat(hooks): add agent and tool lifecycle boundaries #18889

Open

Uh oh!

Conversation

mverrilli commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Hooks Added

Session Lifecycle Events

Session Maintenance Events

Agent Execution Events

Key Features

Complete Session Coverage

Rich Event Context

Hook Message System

Lifecycle Patterns

Bug Fixes

Documentation

Testing

Use Cases

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

mverrilli commented Feb 3, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot commented Feb 3, 2026

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot commented Feb 3, 2026

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mverrilli commented Feb 5, 2026

Uh oh!

mverrilli commented Feb 2, 2026 •

edited

Loading

mverrilli commented Feb 13, 2026 •

edited

Loading