[plugin sdk] docs: plugin host hook RFC#71731
[plugin sdk] docs: plugin host hook RFC#71731100yenadmin wants to merge 10 commits intoopenclaw:mainfrom
Conversation
Greptile SummaryThis is a docs-only RFC PR that adds a full maintainer packet for the generic host hooks required to make Plan Mode a first-class bundled plugin, without merging any implementation. The public index page is correctly placed under a new "Plugin design RFCs" nav group (not "SDK reference"), both new pages carry Confidence Score: 5/5Safe to merge — docs-only change with no runtime impact and no unresolved issues. All three files are documentation only. The previous concern about RFC placement under SDK reference has been resolved: the page now lives under Plugin design RFCs. Both public-facing pages carry explicit Warning callouts, the internal RFC follows the same docs/plan/ pattern as existing maintainer documents, and the PR description confirms link and lint checks passed. No P1 or P0 findings. No files require special attention. Reviews (2): Last reviewed commit: "docs: clarify PR 71676 evidence paths" | Re-trigger Greptile |
There was a problem hiding this comment.
Pull request overview
Adds a tracked RFC doc describing the generic host seams needed to migrate Plan Mode into a first-class bundled plugin, and exposes that doc in the plugin SDK reference navigation so it can be reviewed as an upstream artifact.
Changes:
- Added a new RFC bundle page outlining six host hook areas (session extensions, turn injections, tool policy/metadata, commands/continuation, Control UI slots, agent events/scheduler lifecycle).
- Wired the new page into the “Plugins → SDK reference” navigation in
docs/docs.json.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/plugins/plan-mode-plugin-host-hooks.md | New RFC doc capturing the proposed generic host hook surfaces and acceptance-test expectations for a future Plan Mode plugin port. |
| docs/docs.json | Adds the new RFC page to the Plugins SDK reference navigation. |
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
SDK research follow-up added in Direct status:
Audit split:
Bottom line: current OpenClaw has useful adjacent hooks ( |
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
|
Cleanup pass pushed in Addressed the maintainer-readiness issues from the audit:
Local verification still passes:
CI has restarted on the new head and is still running at the time of this comment. |
|
Codex automated review: keeping this open. Keep open. Current main now has the generic host-hook foundation and stable SDK docs from merged #72287, but this PR is still paired with active same-author follow-up work and the open #71736 Control UI design thread. Closing this PR now would split an active RFC/docs stack rather than perform conservative cleanup. Best possible solution: Keep this PR open for maintainer handling. The best path is to let maintainers decide whether the RFC docs should be closed after #72287 as superseded, folded into #72333, or narrowed around the still-open Control UI/workflow follow-ups after #71736, #72383, and #72333 are resolved. What I checked:
Remaining risk / open question:
Codex Review notes: model gpt-5.5, reasoning high; reviewed against bdba90a20b2b. |
…t shape Address Copilot review pass on PR openclaw#71731: - registerToolPolicy sketch: add trust: "bundled" so the bundled-only contract is visible at the index page. - registerToolMetadata sketch: switch displayName/ui to title/display (plus keep category and safety) to match the RFC packet. - Run-context API: replace api.setRunContextData/getRunContextData with ctx.runContext.set/get to match the RFC packet. - ToolPolicyDecision: change { allow?: true } to { allow: true } so the union discriminates cleanly without an empty-object collision. - Section headers: rename ## RFC 1..6 to ## RFC A..F so they align with the "Filed RFC issues" table earlier in the same page (openclaw#71732..openclaw#71737).
Per copilot review on plan-mode-plugin-host-hooks.md:389-390 — the index page sketch took an explicit `runId` parameter while the RFC packet itself (docs/plan/plan-mode-plugin-host-hooks-rfc.md:1022-1027) defines the contract as implicitly scoped to the current run via `set/get(key)`. Align the index page with the packet so readers don't see two different shapes for the same proposed contract.
| | C | Normal `before_tool_call`, core config filtering, basic plugin tool catalog fields. | Normal hooks share plugin ordering; there is no bundled/trusted pre-plugin policy tier, metadata/display registry, or core-tool decoration rule. | budget guards, workspace policy, deploy freezes, dangerous-action approvals | | ||
| | D | `api.registerCommand(...)`, `gatewayClientScopes` in context, scoped plugin gateway methods. | Plugins can inspect scopes manually, but commands cannot declare host-enforced scopes, trusted reserved-root ownership, or `continueAgent`. | deploy approvals, review commands, budget overrides, incident commands, channel commands | | ||
| | E | Remote slash commands and generic plugin approval cards. | Existing UI support covers discovery and one generic card class, not chat modes, input guards, status surfaces, event classifiers, or descriptor projection. | approval workflows, release dashboards, budget warnings, incident banners, memory panels | | ||
| | F | Raw `runtime.events.onAgentEvent`, internal run context, `gateway_start.getCron`, prompt hooks. | Plugins lack typed filtered event subscriptions, namespaced run context, session-owned scheduler cleanup, and heartbeat contribution ordering. | telemetry exporters, memory indexers, CI watchers, incident escalators, long-running jobs | |
| Existing `gateway_start.getCron` can remain for low-level cron access, but Plan | ||
| Mode needs session lifecycle cleanup and consistent ownership. |
| - Provide run-scoped plugin data that is cleaned up when the run completes. | ||
| - Let session extension lifecycle clean up cron or heartbeat jobs. | ||
| - Let heartbeat prompt assembly ask enabled plugins for additive prompt text. | ||
| - Keep existing `gateway_start.getCron` behavior for lower-level cron access. |
|
Closing to make space PR wise |
Summary
This PR is the maintainer RFC/decision artifact for making Plan Mode a first-class bundled plugin without merging the large host patch from #71676.
RFC Status Warning
This is proposed SDK design, not implemented SDK reference. The docs include explicit warning callouts, and the public page has been moved out of
SDK referenceinto a dedicatedPlugin design RFCsnav group.Decision This PR Asks Maintainers To Make
This RFC defines the complete host-hook contract. The follow-up implementation PR must implement all generic hooks needed before Plan Mode can be packaged as a bundled plugin and audited against #71676 for parity.
The implementation PR should be one focused host-hook PR with generic SDK contracts and fixture tests. It should not include Plan Mode product prompts, Plan Mode tools, Plan Mode command text, Plan Mode CSS, Telegram-specific Plan Mode behavior, local installer patch logic, or Smarter-Claw compatibility code.
RFC Decision Threads
Each issue body now includes: proposed/not-implemented status, current SDK surface, why that surface is adjacent but insufficient, proposed seam, Plan Mode parity use, reusable non-Plan plugin examples, decisions needed, and fixture acceptance criteria.
Already Implemented? Standard
Use the #71427 closure standard: an existing hook only resolves an RFC if it owns the same lifecycle boundary, payload shape, ordering, authorization, disablement, cleanup, and fixture-test semantics.
Current OpenClaw has useful adjacent surfaces (
before_prompt_build,before_tool_call, plugin commands, plugin gateway RPCs, generic plugin approvals, raw runtime events, andgateway_start.getCron). These do not provide the exact SDK contracts required here.RFC Contents
The full RFC packet covers:
Change Type
Scope
Linked Issue/PR
Verification
Verified locally:
pnpm format:docs:checkpnpm lint:docspnpm docs:check-mdxpnpm docs:check-linksHuman Verification
Compatibility / Migration
Risks and Mitigations
Plugin design RFCsnav placement.Next Step After This PR
Implement the generic host hooks described here in one focused follow-up PR with SDK types, gateway protocol support, runner integration, lifecycle cleanup, and a tiny SDK contract fixture. After that lands, Plan Mode can move into a bundled plugin and be audited against #71676 for 100% parity.