Bug: Plugin lifecycle hooks (api.on) never fire due to initialization timing

Summary

Plugin lifecycle hooks registered via api.on() are never invoked during agent interactions, despite successful registration and no error messages.

Environment

• OpenClaw version: v2026.3.13 (61d171a)
• Node.js: v22.22.1
• OS: Ubuntu 24.04
• Plugin: lobster-press v4.0.42

Steps to Reproduce

1. Create a plugin with lifecycle hooks:

   export default function register(api) {
     api.on("before_agent_start", async (event, ctx) => {
       console.log("[plugin] before_agent_start hook fired");
       return { prependContext: "test" };
     });
     
     api.on("agent_end", async (event, ctx) => {
       console.log("[plugin] agent_end hook fired");
     });
   }

2. Configure plugin in openclaw.json:

   {
     "plugins": {
       "allow": ["my-plugin"],
       "entries": {
         "my-plugin": { "enabled": true }
       }
     }
   }

3. Start OpenClaw Gateway

4. Send messages to agent

5. Check logs

Expected Behavior

• [plugin] before_agent_start hook fired should appear in logs
• [plugin] agent_end hook fired should appear after agent completes
• Hooks should be called for every agent interaction

Actual Behavior

Logs show:

[my-plugin] Plugin loaded
[my-plugin] Lifecycle hooks registered (before_agent_start + agent_end)

Missing:

• No "hook fired" logs ever appear
• No "hook runner initialized" logs
• hookRunner.hasHooks("agent_end") returns false
• Database operations in hooks never execute

Root Cause Analysis

After examining OpenClaw source code, I identified a timing issue in the plugin loading sequence:

// From compact-D3emcZgv.js
function loadOpenClawPlugins(options = {}) {
  const { registry, createApi } = createPluginRegistry({...});
  // ...
  activatePluginRegistry(registry, cacheKey);  // ← initializeGlobalHookRunner() called here
}

function activatePluginRegistry(registry, cacheKey) {
  setActivePluginRegistry(registry, cacheKey);
  initializeGlobalHookRunner(registry);  // ← registry.typedHooks is EMPTY at this point
}

Sequence of events:

1. createPluginRegistry() creates empty registry with typedHooks = []
2. activatePluginRegistry() → initializeGlobalHookRunner() (registry still empty)
3. Plugin register() functions are called
4. api.on() → registerTypedHook() → registry.typedHooks.push() (TOO LATE!)
5. hookRunner.hasHooks() checks the registry snapshot from step 2 (always returns false)

Evidence:

• No "hook runner initialized" log (because registry.hooks.length === 0)
• registry.typedHooks is populated AFTER globalHookRunner is created
• hasHooks() uses the empty registry

Why It Matters

This affects any plugin trying to use lifecycle hooks for:

• Memory management (capture/recall at session boundaries)
• Context injection (prepending context before agent starts)
• Audit logging (tracking agent interactions)
• Resource cleanup (releasing resources after agent ends)

Workaround

Currently, the only workaround is to use MCP tools directly instead of lifecycle hooks, requiring manual invocation by users.

Proposed Fix

Two possible approaches:

Option 1: Defer hookRunner initialization Move initializeGlobalHookRunner() to after all plugins' register() functions complete.

Option 2: Use live registry reference Make hookRunner.hasHooks() check the live registry.typedHooks instead of a snapshot.

Related Information

• pluginHookNameSet includes "agent_end" (hook name is valid)
• registerTypedHook() works correctly (no "unknown typed hook" warnings)
• memory-lancedb plugin uses identical api.on() pattern

Test Case

I can provide access to a test machine (192.168.11.219) with the failing configuration for debugging.