feat(hooks): add agent and tool lifecycle boundaries by vincentkoc · Pull Request #12583 · openclaw/openclaw

vincentkoc · 2026-02-09T10:34:14Z

Why

Agent execution lacked complete lifecycle boundaries around thinking, response generation, and tool execution, reducing traceability for observability and policy systems. This PR adds those boundaries and ensures tool lifecycle hooks carry toolCallId context when available. lobster-biscuit

Split Context

This PR was split from closed umbrella PR #9761: #9761.

Detailed Changes

Added internal agent lifecycle hook emissions:
- agent:thinking:start / agent:thinking:end
- agent:response:start / agent:response:end
- agent:tool:start / agent:tool:end
Added runAfterToolCallHook wiring for tool execution lifecycle completion
Propagated toolCallId through before/after tool hook contexts where available
Extended client tool definition adapter to pass toolCallId and run after-tool hook flow
Added focused tests for agent lifecycle emissions and tool lifecycle behavior

Greptile Overview

Greptile Summary

This PR adds explicit lifecycle boundaries around embedded agent execution and tool calls.

Introduces internal hook emissions for agent model thinking and response generation (agent:thinking:*, agent:response:*) inside the embedded attempt runner, with a run-scoped fallback session key when sessionKey is missing.
Adds internal + plugin tool lifecycle boundaries by emitting agent:tool:start/agent:tool:end around tool execution, and wiring after_tool_call via a new runAfterToolCallHook.
Propagates and normalizes toolCallId through tool hook contexts. When upstream toolCallIds are missing/blank, wrappers generate a canonical hook-<uuid> ID and use it consistently.
Updates client tool adapter to always run after_tool_call in a finally block and include toolCallId in the pending tool result.
Adds focused tests validating the new lifecycle emissions and tool hook propagation.

Overall, the changes fit into the existing hooks architecture by expanding internal hook events for observability and enhancing plugin hook context for tool lifecycle correlation.

Confidence Score: 5/5

This PR is safe to merge with minimal risk.
Changes are localized to hook/tool lifecycle wiring, include consistent toolCallId fallback behavior, and add targeted tests. I did not find any new must-fix functional regressions in the changed paths beyond already-discussed review threads.
No files require special attention

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

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

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

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

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

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-09T19:16:08Z

Additional Comments (1)

src/agents/pi-embedded-runner/run.ts
Client toolCallId dropped
runEmbeddedAttempt now returns clientToolCall.toolCallId, but this code ignores it and generates a new pending tool id via ``id: call_${Date.now()}```. For client-delegated tools, this breaks correlation between the returned pendingToolCalls[].id` and the tool lifecycle hooks (`before_tool_call`/`after_tool_call` + internal `agent:tool:*`) that use the real `toolCallId`. Consider using `attempt.clientToolCall.toolCallId` for `pendingToolCalls[].id` so downstream consumers can correlate consistently.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agents/pi-embedded-runner/run.ts
Line: 846:852

Comment:
**Client toolCallId dropped**
`runEmbeddedAttempt` now returns `clientToolCall.toolCallId`, but this code ignores it and generates a new pending tool id via ``id: `call_${Date.now()}```. For client-delegated tools, this breaks correlation between the returned `pendingToolCalls[].id` and the tool lifecycle hooks (`before_tool_call`/`after_tool_call` + internal `agent:tool:*`) that use the real `toolCallId`. Consider using `attempt.clientToolCall.toolCallId` for `pendingToolCalls[].id` so downstream consumers can correlate consistently.

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

vincentkoc · 2026-02-09T19:26:49Z

runEmbeddedAttempt now returns clientToolCall.toolCallId, but this code ignores it and generates a new pending tool id via id: call_${Date.now()}```. For client-delegated tools, this breaks correlation between the returned ``pendingToolCalls[].id and the tool lifecycle hooks (before_tool_call`/`after_tool_call` + internal `agent:tool:*`) that use the real `toolCallId`. Consider using `attempt.clientToolCall.toolCallId` for `pendingToolCalls[].id` so downstream consumers can correlate consistently.

@greptileai used call_${Date.now()} instead of the actual client tool call id as you suggested.

greptile-apps · 2026-02-09T19:27:27Z

Perfect! The fix looks correct. Using attempt.clientToolCall.toolCallId on line 849 ensures the same ID flows through the entire lifecycle:

Before (broken correlation):

Tool lifecycle hooks: toolCallId = "hook-abc123"  
Returned pendingToolCalls: id = "call_1234567890"  ❌ mismatch

After (consistent correlation):

Tool lifecycle hooks: toolCallId = "hook-abc123"  
Returned pendingToolCalls: id = "hook-abc123"  ✅ same ID

This maintains the correlation chain established in src/agents/pi-tool-definition-adapter.ts:151 where the ID is first generated/captured, through the hook system, and now to the consumer-facing pendingToolCalls metadata.

The change is minimal, safe, and directly addresses the observability gap you identified.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

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

vincentkoc · 2026-02-09T19:34:04Z

@greptileai Tool hook ID fallback generation updated as per your ask to use attempt.clientToolCall.toolCallId?.trim() || \call_${Date.now()} which resolves the final issue. Please update PR score if good to merge.

openclaw-barnacle · 2026-02-17T04:51:00Z