Summary

Add a namespaced plugin session extension API so plugins can persist typed per-session state, expose an explicit public projection to gateway/UI clients, and mutate that state through gateway-authorized patch actions.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode is the forcing case: PR #71676 adds root SessionEntry fields and hardcoded sessions.patch behavior. A first-class plugin needs the same durability, validation, projection, broadcast, and lifecycle behavior without Plan Mode-specific core fields.

The same host seam is reusable for any plugin that owns per-session workflow state: review gates, release/deploy workflows, memory/context managers, incident/ticket bots, cost governors, channel bindings, telemetry exporters, and workspace policy plugins.

Current SDK surface

OpenClaw currently has fixed core session state, fixed sessions.patch, hardcoded gateway session rows, an internal post-write session:patch hook, and plugin gateway RPCs with declared scopes.

Those surfaces are useful but insufficient: a plugin can expose a separate RPC, but it cannot register typed session state that participates in native session patch, projection, broadcast, reset, delete, compaction, and disabled-plugin semantics.

Proposed solution

Add a generic registration surface such as:

api.registerSessionExtension({
  key,
  schema,
  publicProjection,
  patchActions,
  lifecycle,
});

Patch routing can be either a dedicated sessions.pluginPatch method or an additive sessions.patch.plugin envelope. Maintainers should choose one shape before implementation.

Reusable plugin examples

• Plan Mode stores mode, approval status, question state, pending injection ids, blocking subagent ids, and nudge job ids.
• Review gates store PR id, unresolved findings, reviewer decisions, and merge gate state.
• Release plugins store environment, rollout phase, freeze window, and rollback id.
• Memory plugins store pins, recall cursors, compaction policy, and source visibility.
• Budget governors store spend counters, thresholds, override decisions, and expiry.
• Channel plugins store thread bindings, delivery preferences, and auth handoff state.
• Incident bots store severity, owner, ticket sync cursor, and SLA deadline.

Decisions needed

• sessions.pluginPatch method vs sessions.patch.plugin envelope.
• Public projection shape for session list/detail rows.
• Patch action schema and handler typing.
• Lifecycle hooks for reset, delete, compaction, migration, and plugin disablement.
• Stable error codes for unknown plugin, unknown action, invalid payload, disabled plugin, and handler failure.
• Gateway scope declaration and host enforcement model for patch actions.

Acceptance criteria

• A fixture plugin can persist extension state.
• Invalid payload fails closed without writing state.
• Public projection appears in session rows/details.
• Private extension fields do not leak.
• Reset/delete/compaction lifecycle clears extension state.
• Disabled plugin extension cannot be patched or projected.
• Gateway scopes are enforced by the host before the plugin handler runs.

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 session-extension slice, #72287 carries the core plugin-owned session extension foundation; #73384 exercises workflow/session-action projection and Gateway normalization; #74483 adds the follow-up SessionEntry slot projection surface.