feat(hooks): fixed and adding various agent, messaging, system and compaction hooks by vincentkoc · Pull Request #9761 · openclaw/openclaw

vincentkoc · 2026-02-05T16:56:50Z

This PR adds and wires missing lifecycle hooks across OpenClaw (internal hooks and plugin hooks) to unlock observability, guardrails, and monitoring. Also patched CI/CD to ensure formatter passes.

New/expanded internal hooks (`HOOK.md`)

session:compact:before / session:compact:after (compaction lifecycle)
session:prune (context pruning of tool outputs)
gateway:shutdown / gateway:pre-restart (gateway lifecycle)
agent:thinking:start / agent:thinking:end (model call boundary)
agent:response:start / agent:response:end (response generation boundary)
agent:tool:start / agent:tool:end (tool execution boundary)

Plugin hooks wired

before_compaction / after_compaction now called in the compaction pipeline
message_received / message_sending / message_sent wired into outbound delivery
before_tool_call / after_tool_call now receive toolCallId when available

Fixes and other context improvements

Formatter was not matching with CI/CD based pnpm format
Session keys are treated as case-insensitive identifiers across routing/storage
Message hook context now includes sessionKey/sessionId
Tool hook context now includes toolCallId
Compaction hook context now includes counts and token metadata
Upstream test session-write-lock failures + unhandled process.exit caused by ec0728b35 (fix: release session locks on process termination [AI-assisted] #1962)
Upstream test dispatch-from-config onToolResult expectation failures caused by 05b28c147 ee1ec3fab (fix: wire onToolResult callback for verbose tool summaries #2022)
Upstream test Telegram native slash command count drift same onToolResult behavior change from 05b28c147 + ee1ec3fab

Issues addressed

fix Broken formatter issues in c/cd:
- [Bug]: oxmft on github ci/cd not matching local #9836
fix: Missing message:received/sent hooks wired:
- Feature Request: Implement message:received and message:sent hooks #8807
- feat(hooks): bridge plugin message hooks to internal hooks system #9387
feat: Expose message lifecycle hooks in plugin API:
- Feature Request: Expose message lifecycle hooks in Plugin API #9524
feat: Bridge message_received to internal hooks:
- Feature Request: Bridge message_received to internal hooks system (workspace hooks) #7067
feat: Propagate tool before/after hooks with toolCallId:
feat: Plugin hook runner now receives these new events:
feat: Pre and post compaction lifecycle now exposed (internal and plugin hooks)
feat: Add context pruning hooks (internal):
- Feature request: Hook event for context pruning #8606
feat: Gateway lifecycle hooks added:
- Feature request: gateway:shutdown and gateway:pre-restart hook events #6711
feat: New agent lifecycle hooks for thinking/response/tool boundaries (internal):
- Feature Request: Agent loop lifecycle hooks (thinking, response, message events) #7724
feat: partial or full fix by cleaner implementation of sessionKey usage in hooks:
- [Feature]: Expose sessionKey to PluginCommandContext #9871

FYI

Compaction hooks currently report metadata only (not full message snapshots).
Pruning hook reports counts/tool names only (not pruned content).

Greptile Overview

Greptile Summary

This PR expands OpenClaw’s lifecycle hook surface area and wires plugin hooks into core workflows. Key changes include:

Adds internal hook emissions for session compaction (session:compact:before/after), context pruning (session:prune), gateway shutdown/restart (gateway:shutdown, gateway:pre-restart), and agent lifecycle boundaries (agent:thinking:*, agent:response:*, agent:tool:*).
Wires plugin hooks for compaction and outbound messaging (message_sending, message_sent) and extends tool hook context to include toolCallId.
Normalizes session keys as case-insensitive identifiers via a shared normalizeSessionKey helper and propagates sessionKey/sessionId through outbound delivery paths.
Adds test coverage around new hook lifecycles (compaction hooks, agent response/thinking hooks, gateway close hooks) and adjusts existing tests for async pruning.

Overall, the PR is centered on improving observability/guardrails by ensuring lifecycle hooks fire consistently across internal and plugin APIs, while also tightening session key handling for routing/storage consistency.

Confidence Score: 3/5

This PR is moderately safe to merge, but has a couple of correctness risks around hook attribution and async extension handler semantics.
Most changes are additive hook wiring and test updates, but there are two areas that can cause real runtime behavioral issues: (1) internal hook events fabricating sessionKey-like values (can break attribution/routing assumptions for consumers), and (2) context pruning now relies on an async extension handler, which will break pruning if the host does not await Promises. The rest of the hook wiring appears guarded and best-effort with tests covering key lifecycles.
src/agents/pi-extensions/context-pruning/extension.ts, src/agents/pi-tools.before-tool-call.ts, src/agents/pi-embedded-runner/compact.ts

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

src/agents/pi-embedded-runner/run.ts

src/agents/pi-embedded-runner/compact.ts

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

src/infra/outbound/deliver.ts

src/agents/pi-tools.before-tool-call.ts

vincentkoc · 2026-02-06T01:49:15Z

@greptileai

greptile-apps

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/agents/pi-tool-definition-adapter.ts

greptile-apps · 2026-02-06T01:54:53Z

Additional Comments (2)

src/infra/outbound/deliver.ts
message_sent not fired

deliverOutboundPayloads() emits message_sent after sendTextChunks()/sendSignalTextChunks() and inside the media loop, but the early-return path for handler.sendPayload && payload.channelData only calls message_sent on success. If handler.sendPayload(payload) throws, the catch will run runMessageSentHook(attemptedSendContent, false, ...), but attemptedSendContent is initialized from the pre-hook payloadSummary.text and doesn’t track per-channelData payload content after message_sending mutation. This makes message_sent report stale content for failures on sendPayload channels.

Set attemptedSendContent after applying message_sending (and/or right before each send attempt) so failure hooks report the same content that was actually attempted.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/infra/outbound/deliver.ts
Line: 232:235

Comment:
**message_sent not fired**

`deliverOutboundPayloads()` emits `message_sent` after `sendTextChunks()`/`sendSignalTextChunks()` and inside the media loop, but the early-return path for `handler.sendPayload && payload.channelData` only calls `message_sent` on success. If `handler.sendPayload(payload)` throws, the `catch` will run `runMessageSentHook(attemptedSendContent, false, ...)`, but `attemptedSendContent` is initialized from the *pre-hook* `payloadSummary.text` and doesn’t track per-channelData payload content after `message_sending` mutation. This makes `message_sent` report stale content for failures on `sendPayload` channels.

Set `attemptedSendContent` after applying `message_sending` (and/or right before each send attempt) so failure hooks report the same content that was actually attempted.


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

src/agents/pi-extensions/context-pruning/pruner.ts
Prune hook await changes

pruneContextMessages() is now async solely to await triggerInternalHook via emitPruneHook(). This makes every pruning pass wait on hook handlers, which can slow the agent loop and (if hooks hang) block prompt execution. Since the hook is best-effort telemetry, consider firing it without awaiting (e.g., void triggerInternalHook(...) with .catch(...)) or using a timeout so pruning remains deterministic.

This is especially relevant because pruning runs in the context extension on every turn when enabled.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/pi-extensions/context-pruning/pruner.ts
Line: 266:268

Comment:
**Prune hook await changes**

`pruneContextMessages()` is now `async` solely to `await triggerInternalHook` via `emitPruneHook()`. This makes every pruning pass wait on hook handlers, which can slow the agent loop and (if hooks hang) block prompt execution. Since the hook is best-effort telemetry, consider firing it without awaiting (e.g., `void triggerInternalHook(...)` with `.catch(...)`) or using a timeout so pruning remains deterministic.

This is especially relevant because pruning runs in the `context` extension on every turn when enabled.


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

vincentkoc · 2026-02-06T02:14:47Z

@greptileai

greptile-apps

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/agents/pi-embedded-runner/compact.ts

greptile-apps · 2026-02-06T02:17:26Z

Additional Comments (2)

src/agents/pi-tools.before-tool-call.ts
Tool hook sessionKey misuse

resolveHookSessionKey() fabricates a sessionKey like tool:<agentId>:<toolCallId> when ctx.sessionKey is missing (src/agents/pi-tools.before-tool-call.ts:1704-1718). This makes internal agent:tool:* hooks look like they’re attached to a real session key and can collide across runs if toolCallIds repeat, breaking routing/attribution for any consumer that treats sessionKey as a persisted identifier. Consider using a clearly non-session key (e.g. run:<runId> like attempt.ts does) or leaving sessionKey empty and putting the fallback into context only.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/pi-tools.before-tool-call.ts
Line: 1704:1718

Comment:
**Tool hook sessionKey misuse**

`resolveHookSessionKey()` fabricates a `sessionKey` like `tool:<agentId>:<toolCallId>` when `ctx.sessionKey` is missing (`src/agents/pi-tools.before-tool-call.ts:1704-1718`). This makes internal `agent:tool:*` hooks look like they’re attached to a real session key and can collide across runs if toolCallIds repeat, breaking routing/attribution for any consumer that treats `sessionKey` as a persisted identifier. Consider using a clearly non-session key (e.g. `run:<runId>` like `attempt.ts` does) or leaving `sessionKey` empty and putting the fallback into `context` only.

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

src/agents/pi-extensions/context-pruning/extension.ts
Async handler may be ignored

contextPruningExtension changed the api.on("context", ...) handler to async (src/agents/pi-extensions/context-pruning/extension.ts:1413-1416). If the underlying extension host expects a synchronous return value (common for hook-style APIs), returning a Promise can cause the pruned messages to be ignored (or applied too late), meaning pruning silently stops working in production. This needs confirmation against the ExtensionAPI.on contract; if it’s sync-only, keep the handler synchronous and avoid awaiting inside it. Does the pi-coding-agent ExtensionAPI.on("context") contract support async handlers (i.e., does it await Promises)? If not, we need to keep pruning synchronous and remove async/await here.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/pi-extensions/context-pruning/extension.ts
Line: 1413:1416

Comment:
**Async handler may be ignored**

`contextPruningExtension` changed the `api.on("context", ...)` handler to `async` (`src/agents/pi-extensions/context-pruning/extension.ts:1413-1416`). If the underlying extension host expects a synchronous return value (common for hook-style APIs), returning a Promise can cause the pruned `messages` to be ignored (or applied too late), meaning pruning silently stops working in production. This needs confirmation against the `ExtensionAPI.on` contract; if it’s sync-only, keep the handler synchronous and avoid awaiting inside it. Does the pi-coding-agent ExtensionAPI.on("context") contract support async handlers (i.e., does it await Promises)? If not, we need to keep pruning synchronous and remove async/await here.

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

cpojer · 2026-02-06T02:25:16Z

This is too big. Make small PRs. Stop spamming me.

vincentkoc · 2026-02-09T22:21:16Z

This is too big. Make small PRs. Stop spamming me.

@cpojer As requested, PR has been split and child PRs are ready

vincentkoc · 2026-02-15T04:03:29Z

Moved to #16788

vincentkoc added 9 commits February 5, 2026 08:35

feat(hooks): adding outbound messagesent hook

d8a43d3

feat(hooks): outbound messagesent hooks

495a8cd

chore(hooks): wiring session keys to heatbeat hooks

9bae626

chore(hooks): wiring sessionkey to outbound session hooks

7ce8b01

chore(hooks): wiring sessionkey to messaging hooks

b22aca7

chore(hooks): includes and type changes

8e5caac

feat(hooks): adding runAfterToolCallHook

1a1e6b0

feat(hooks): adding runAfterToolCallHook

f427ed2

docs(hooks): updating documentation on hooks

eafd8c0

openclaw-barnacle bot added docs Improvements or additions to documentation gateway Gateway runtime commands Command implementations agents Agent runtime and tooling labels Feb 5, 2026

vincentkoc added 7 commits February 5, 2026 09:09

feat(hooks): add compaction events

0ddfb55

feat(hooks): add missing agent internal hooks

c98ac13

feat(hooks): add context pruning hooks

f8bf9f8

feat(hooks): add internal tool events

bbffe4b

feat(hooks): add shutdown events

915d87c

docs(hooks): update hooks docs

0e8924f

Update pi-tools.before-tool-call.test.ts

df3af67

vincentkoc added 4 commits February 5, 2026 09:25

chore: lint

d2f7ee3

test(hooks): lint and extend hooks

df41c92

Update pi-tools.before-tool-call.ts

7b34881

test(hooks): extend hooks

9c6e99a

Merge branch 'main' into vk/otel-plugin-hooks

a13e93d

greptile-apps bot reviewed Feb 6, 2026

View reviewed changes

src/agents/pi-embedded-runner/run.ts Show resolved Hide resolved

src/agents/pi-embedded-runner/compact.ts Show resolved Hide resolved

vincentkoc added 2 commits February 5, 2026 17:12

fix: use UUID when no toolcallId

9192c40

chore: reesolve test issues

899854b

openclaw-barnacle bot removed the channel: telegram Channel integration: telegram label Feb 6, 2026

greptile-apps bot reviewed Feb 6, 2026

View reviewed changes

src/infra/outbound/deliver.ts Show resolved Hide resolved

src/agents/pi-tools.before-tool-call.ts Show resolved Hide resolved

chore: sessionid fallbacks greptile

d1c83d9

greptile-apps bot reviewed Feb 6, 2026

View reviewed changes

src/agents/pi-tool-definition-adapter.ts Show resolved Hide resolved

chore: greptile

0ecf223

greptile-apps bot reviewed Feb 6, 2026

View reviewed changes

src/agents/pi-embedded-runner/compact.ts Show resolved Hide resolved

This was referenced Feb 6, 2026

fix: wire onToolResult callback for verbose tool summaries #2022

Merged

fix: release session locks on process termination [AI-assisted] #1962

Merged

cpojer closed this Feb 6, 2026

vincentkoc mentioned this pull request Feb 15, 2026

feat(hooks): emit compaction lifecycle hooks #16788

Open

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

vincentkoc commented Feb 5, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New/expanded internal hooks (HOOK.md)

Plugin hooks wired

Fixes and other context improvements

Issues addressed

FYI

Greptile Overview

Greptile Summary

Confidence Score: 3/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

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!

vincentkoc commented Feb 6, 2026

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot commented Feb 6, 2026

Uh oh!

vincentkoc commented Feb 6, 2026

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot commented Feb 6, 2026

Uh oh!

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

Uh oh!

Uh oh!

vincentkoc commented Feb 9, 2026

Uh oh!

vincentkoc commented Feb 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

vincentkoc commented Feb 5, 2026 •

edited by greptile-apps bot

Loading

New/expanded internal hooks (`HOOK.md`)

cpojer commented Feb 6, 2026 •

edited

Loading