Problem

Internal hooks (like the Mission Control hook) cannot access agent lifecycle events because of module instance isolation.

The hook's handler.ts attempts to import onAgentEvent from agent-events.js, but:

1. The file paths searched by the hook (dist/infra/agent-events.js) don't exist — the actual export is in dist/extensionAPI.js
2. Even if the correct path is found, the hook imports a separate module instance from the gateway's instance
3. Events emitted by the gateway's instance never reach the hook's listeners

The hook's README acknowledges this as a known issue:

Module instance isolation — The hook may import a separate instance of agent-events.js and not receive events from the gateway's instance.

Current Behavior

• Hook installs and registers correctly (openclaw hooks list shows ready)
• Gateway loads the hook handler (loaded 1 internal hook handler)
• But zero hook handler output appears in logs — the onAgentEvent listener never fires
• The hook checks for globalThis.__openclawAgentEvents but OpenClaw doesn't set it

Expected Behavior

Hooks should be able to subscribe to agent lifecycle events (start, end, error, tool usage) to enable integrations like dashboards, logging, and external task tracking.

Proposed Solutions

Option 1: Expose via Hook Context (Recommended)

Pass the gateway's event system to hooks through the event context:

const handler = await import(hookPath);
await handler.default({
  ...event,
  api: {
    onAgentEvent: gatewayOnAgentEvent // Shared instance
  }
});

Option 2: Set Global Event Bus

OpenClaw sets the global on startup (hook already checks for this):

globalThis.__openclawAgentEvents = {
  onAgentEvent: sharedOnAgentEvent
};

Option 3: Hook-specific Event Subscription Config

Allow hooks to declare event subscriptions in HOOK.md metadata and have the gateway deliver matching events directly.

Environment

• OpenClaw: 2026.2.2-3
• OS: macOS 26.2 (arm64)
• Node: v25.5.0
• Hook: mission-control (from openclaw-mission-control repo)

Related

• openclaw-mission-control — the dashboard that depends on this integration