openclaw - 💡(How to fix) Fix Bug: before_agent_finalize hook never fires for OpenClaw agents (main, coder, etc.)

Summary

api.on("before_agent_finalize", ...) registered via Plugin SDK never fires for OpenClaw agents (main, coder, etc.) — the hook is only reachable through the native relay harness path.

Actual behavior

In a plugin:

api.on("before_agent_finalize", async (event, ctx) => {
  console.log("this never runs");
  return { action: "continue" };
});

The handler is never invoked during normal agent execution. The hook simply does not fire.

Expected behavior

before_agent_finalize should fire before the agent finalizes its turn, allowing plugins to inspect the last assistant message and optionally request a revision via { action: "revise" }.

Evidence

The hook infrastructure is fully implemented:

• hook-runner-global — defines runBeforeAgentFinalize, wired through runModifyingHook
• lifecycle-hook-helpers — implements runAgentHarnessBeforeAgentFinalizeHook with full revise/finalize/continue logic
• native-hook-relay — processNativeHookRelayInvocation dispatches before_agent_finalize events, and this path works

However, runAgentHarnessBeforeAgentFinalizeHook is only called from native-hook-relay — the native relay harness path.

In the normal agent execution path, the handleAgentEnd function (in the embedded subscribe handler) processes agent termination but never calls runAgentHarnessBeforeAgentFinalizeHook:

handleAgentEnd → status checks → agent_end hook → done
                ↑ no before_agent_finalize call

The hook is simply not wired into the standard OpenClaw agent lifecycle.

Scope

• Affects: all OpenClaw agents (main, coder, etc.)
• Does NOT affect: native relay harness agents (OpenCode, Claude Code, etc.)
• Version: v2026.5.26 and earlier

Related

• #86849 — similar pattern where hook code existed but the calling path was incomplete (before_prompt_build prependContext stripped into system prompt)