Feature Request: Agent Lifecycle Hooks

Problem

Currently there is no way to automatically execute actions before/after an agent processes a message or spawns a subagent. This forces developers to rely on prompt instructions (unreliable) instead of code.

Proposed Solution

Add configurable lifecycle hooks in openclaw.json:

{
  "agents": {
    "defaults": {
      "hooks": {
        "onMessageReceived": {
          "send": { "buttons": [[{"text": "🛑 Stop", "callback_data": "stop:{{sessionId}}"}]] }
        },
        "onSubagentSpawned": {
          "send": { "message": "⚙️ {{agentName}} started: {{label}}", "buttons": [[{"text": "🛑 Stop", "callback_data": "stop:{{runId}}"}]] }
        },
        "onSubagentFinished": {
          "send": { "message": "✅ {{agentName}} finished." }
        }
      }
    },
    "list": [
      {
        "id": "main",
        "hooks": {
          "onMessageReceived": { ... },
          "onSubagentSpawned": { ... }
        }
      }
    ]
  }
}

Hook Types

Template Variables

• {{sessionId}} — short session ID (8 chars)
• {{sessionKey}} — full session key
• {{runId}} — run UUID
• {{agentId}} — agent id (e.g. "sysadmin")
• {{agentName}} — agent display name
• {{label}} — spawn label

Use Cases

1. Stop button on every spawn — onSubagentSpawned sends inline button with callback_data: "stop:{{sessionId}}". User clicks → callback_data forwarded as text message → main agent kills subagent.

2. Notification on completion — onSubagentFinished sends summary to user.

3. Pre-message indicator — onMessageReceived sends "thinking..." or a cancel button before agent starts processing.

Why This Matters

Without hooks, agent behavior depends entirely on prompt instructions — fragile and inconsistent. Code-level hooks make these behaviors guaranteed and configurable per-agent.

Related: #34921 (persistent inline buttons)