Summary

Extend plugin commands with declarative gateway scopes, trusted command-root ownership, and a continueAgent result for commands that should resume an agent run after handling.

This is proposed SDK surface, not currently implemented API.

Why this matters

Plan Mode /plan accept, /plan revise, and /plan answer must patch plugin state, enqueue a continuation, and resume the agent. Current plugin commands can run handlers, but they do not declare host-enforced scopes and they default to stopping command handling.

The same primitive applies to deploy approvals, review gates, incident/ticket workflows, budget overrides, memory/context actions, workspace policy grants, and channel-specific command adapters.

Current SDK surface

OpenClaw currently has api.registerCommand(...). Command context includes gatewayClientScopes, plugin gateway methods can declare opts.scope, duplicate plugin command registration is blocked, and built-in command roots are reserved.

Those surfaces are useful but insufficient: plugins can self-inspect scopes, but the host does not enforce command requiredScopes before the handler. There is no trusted ownership model for reserved roots and no continueAgent result that resumes an agent run after command-side state changes.

Proposed solution

Extend command registration with fields such as:

api.registerCommand({
  name,
  requiredScopes,
  ownership,
  handler,
});

Extend command results with:

return {
  message,
  continueAgent: true,
  delivery: "ephemeral",
};

Existing plugin commands should preserve current behavior: no requiredScopes means current auth behavior, and no continueAgent means do not resume the agent.

Reusable plugin examples

• Plan Mode uses /plan accept, /plan revise, /plan answer, /plan auto on, and /plan auto off.
• Review plugins use /review approve, /review request-changes, and /review rerun.
• Deployment plugins use /deploy approve, /deploy pause, /rollback, and /release status.
• Budget plugins use /budget override, /budget reset, and /budget status.
• Incident plugins use /incident ack, /incident escalate, and /ticket close.
• Memory plugins use /memory pin, /memory forget, and /context refresh.
• Policy plugins use /policy grant, /policy revoke, and /policy explain.
• Channel plugins use /telegram approve, /slack handoff, and /email summarize.

Decisions needed

• Command scope declaration shape.
• Reserved command ownership model: manifest, runtime, or two-phase ownership.
• continueAgent result semantics.
• Command discovery before plugin runtime activation.
• Text-channel behavior for read-only vs mutating commands.
• Error behavior for insufficient scopes, disabled plugins, and untrusted reserved-root claims.

Acceptance criteria

• Fixture command requiring operator.approvals rejects insufficient scope before handler execution.
• Read-only fixture command works with read scope only.
• Command returning continueAgent: true resumes agent execution.
• Command returning no continuation preserves current behavior.
• Untrusted plugin cannot claim a reserved command root.
• Text-channel command path receives the same scope and continuation semantics.

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 command/session continuation slice, #73384 is the current workflow PR to review for host-mediated session actions, typed action errors, and continueAgent-style workflow continuation semantics.