Summary

Expose safe plugin subscriptions to agent events, namespaced run-scoped plugin context, session-scoped scheduler helpers, and heartbeat prompt contributions.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode parity requires plan snapshot persistence, subagent tracking, run completion cleanup, scheduled nudges, and heartbeat prompt nudges. Plugins need stable helpers for those behaviors without raw event-bus access or manual cron cleanup.

The same primitive applies to telemetry exporters, memory indexers, CI/deploy monitors, incident/ticket bots, channel notification plugins, long-running job monitors, and subagent coordinators.

Current SDK surface

OpenClaw currently has runtime.events.onAgentEvent, internal AgentRunContext, hook contexts with run/session identifiers in some paths, gateway_start.getCron, generic prompt hooks, and heartbeat request helpers.

Those surfaces are useful but insufficient: raw event observation is not a typed lifecycle-owned plugin API; cron access does not provide plugin/session ownership cleanup; prompt hooks are not heartbeat-specific; and there is no namespaced plugin run-context storage that the host cleans on run completion.

Proposed solution

Add typed event subscription and lifecycle helpers such as:

api.onAgentEvent("run_completed", handler);
ctx.runContext.set("plugin-key", value);
ctx.scheduler.createSessionJob({ pluginKey, sessionKey, kind, schedule, payload });
api.on("heartbeat_prompt_contribution", handler);

The host should sanitize event payloads, enforce event access rules, own cleanup on run end/session reset/plugin disablement, and define deterministic heartbeat contribution ordering.

Reusable plugin examples

• Plan Mode persists plan snapshots, tracks blocking subagents, schedules nudges, and contributes heartbeat reminders.
• Telemetry exporters subscribe to sanitized events and batch scheduled exports.
• Memory indexers observe run/tool events and refresh derived context.
• CI watchers poll workflows and inject completion or failure summaries.
• Incident bots schedule SLA escalations and heartbeat unresolved incidents.
• Channel plugins track delivery events and retry failed sends.
• Long-running job monitors poll job state, emit progress, and clean up on session close.
• Subagent coordinators store per-run state and inject follow-up once subagents settle.

Decisions needed

• Event types exposed to plugins and which require trust.
• Run-context storage lifecycle and namespace model.
• Session-scoped scheduler ownership and cleanup model.
• Dedicated heartbeat hook vs heartbeat-scoped agent_turn_prepare.
• Cleanup behavior on run end, cancellation, session reset/delete, gateway restart, and plugin disablement.
• Diagnostics for dropped events, failed jobs, and suppressed heartbeat contributions.

Acceptance criteria

• Fixture plugin observes one sanitized agent event.
• Fixture plugin writes derived extension state from that event.
• Run context data is available during a run and cleaned after completion/cancellation.
• Session reset deletes fixture-owned scheduled jobs.
• Plugin disablement removes fixture jobs and heartbeat contributions.
• Heartbeat contribution appears only when fixture session state requests it.

References

• RFC PR: [plugin sdk] docs: plugin host hook RFC #71731
• Source behavior/parity oracle: Plan Mode rebased onto upstream/main + executing-state subsystem #71676
• Full RFC packet: docs/plan/plan-mode-plugin-host-hooks-rfc.md

Current replacement stack (2026-04-30)

#72082 was the earlier implementation vehicle. Current review should use the merged foundation #72287 plus #73384 and draft #74483. For this lifecycle/events/run-context/scheduler slice, #72287 carries the base lifecycle and host-hook foundation; #73384 exercises scheduler/session-turn workflow behavior and cleanup hardening; #74483 adds follow-up host runtime reads and scheduler tag cleanup.