Summary

Add a host-owned durable queue for plugin next-turn injections plus a typed agent_turn_prepare hook so plugins can schedule future prompt additions with exactly-once semantics.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode approval acceptance, revision, question answering, nudges, and subagent follow-ups must affect a future run exactly once. before_prompt_build can add current-turn context, but it is not durable enough and should not become a pending interaction queue.

The same primitive is useful for plugins that receive an approval, event, timer, channel callback, CI result, ticket update, or memory selection outside the current model call and need to feed the next turn safely.

Current SDK surface

OpenClaw currently has before_prompt_build, legacy before_agent_start, and in-memory system events that can prepend context to a prompt.

Those surfaces are useful but insufficient: they do not provide host-owned storage, exactly-once dequeue, retry-safe consumption, expiry, dedupe, disabled-plugin suppression, or a stable preparation boundary before retry/fallback/provider transforms.

Proposed solution

Expose APIs such as:

api.enqueueNextTurnInjection({
  sessionKey,
  id,
  role,
  content,
  reason,
  expiresAt,
  dedupeKey,
});

api.on("agent_turn_prepare", async (event, ctx) => ({
  prependSystemContext,
  prependUserMessages,
}));

The host owns storage, dequeue timing, prompt ordering, retry/fallback behavior, provider transform ordering, and consumption marking.

Reusable plugin examples

• Plan Mode injects approved execution, revision requests, question answers, scheduled nudges, and subagent follow-ups.
• Review plugins inject required fixes after asynchronous review.
• Deployment plugins inject release checklists or post-approval deploy instructions.
• Memory managers hydrate selected context exactly once before the next call.
• Incident plugins inject escalation or handoff instructions after an SLA timer fires.
• CI plugins inject the next diagnostic step after log fetching completes.
• Channel plugins inject deferred replies or cross-channel follow-ups.
• Budget plugins inject warnings, downgrade guidance, or ask-before-continuing prompts.

Decisions needed

• Storage location for pending injections.
• Dequeue timing relative to command handling, retries, fallback, and provider transforms.
• Prompt ordering relative to before_prompt_build.
• Expiry and dedupe behavior.
• Disabled-plugin behavior for pending injections.
• Diagnostic visibility for dropped, expired, or suppressed injections.

Acceptance criteria

• A fixture plugin enqueues an injection and the next run receives it once.
• Retry/fallback does not duplicate the injection.
• Expired injection is discarded with a diagnostic event.
• Plugin disablement suppresses or removes pending injections.
• Existing before_prompt_build behavior remains compatible and ordered.
• The fixture proves the queue survives the command-to-next-turn boundary.

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 durable next-turn / turn-prep slice, #72287 carries the generic foundation; #73384 exercises queued-injection priority, workflow composition, and bounded finalize-retry behavior; #74483 adds read-only host runtime context that composes with lifecycle surfaces.