Summary

Describe the problem and fix in 2-5 bullets:

• Problem: OpenClaw's Plugin SDK now has many useful host/workflow seams, but the docs did not give plugin authors or AI agents a single product-neutral recipe map for composing them safely.
• Why it matters: without a concrete recipe guide, authors either overfit on Plan Mode, miss the grouped SDK namespaces, or try to patch core for workflows that can now be built as plugins.
• What changed: this PR adds a long-form host-hook recipe page, wires it into docs navigation, links it from the Plugin SDK overview/hooks docs, and refreshes glossary coverage required by docs CI.
• What did NOT change (scope boundary): this is docs-only. It does not change runtime behavior, plugin permissions, Gateway methods, SDK exports, auth/OAuth provider hooks, or any build/package surface.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related [plugin sdk] docs: plugin host hook RFC #71731, [RFC] Plugin session extensions and patch actions #71732, [RFC] Durable next-turn injections and agent turn preparation hooks #71733, [RFC] Trusted tool policy stage and plugin tool metadata #71734, [RFC] Scoped plugin commands, trusted command ownership, and continuation #71735, [RFC] Control UI plugin contribution slots #71736, [RFC] Agent events, run context, scheduler lifecycle, and heartbeat contributions #71737, [plugin sdk] Add generic plugin host-hook contracts #72287
• This PR fixes a bug or regression

Why this PR exists

The SDK surface is no longer just a flat registerTool(...) story. Current OpenClaw has grouped host-hook families for session state, workflow continuation, session controls, agent events, per-run context, and runtime lifecycle cleanup. That is powerful, but it is also easy to misread if the docs only expose API tables.

This PR turns that surface into a recipe book. The new page answers the author-facing question directly:

If I want my plugin to do X, which host-hook contracts do I compose, and what does that look like end-to-end?

The examples are intentionally product-neutral. Plan Mode is one tenant of these seams, not the privileged one. The same contracts can support approval workflows, workspace policy gates, background monitors, setup wizards, review assistants, release workflows, and future bundled plugins.

Reviewer guide

Changed files

How the recipe page is structured

The new page deliberately uses the same structure for every recipe:

1. What it does
2. Contract excerpt
3. Minimal example
4. Diagram
5. Real-world example
6. Common pitfalls

This makes the page usable both for humans and for AI agents that need a stable pattern to follow.

System flow

flowchart LR
  A[Plugin entry: definePluginEntry] --> B[Grouped host-hook APIs]
  B --> C[Session state, actions, UI descriptors]
  B --> D[Next-turn injection, schedules, attachments]
  B --> E[Agent events, run context, lifecycle cleanup]
  C --> F[Workflow plugin recipes]
  D --> F
  E --> F

Documentation routing

flowchart TD
  Start[Plugin author asks: what can I build?]
  Start --> Tools{Only static agent tools?}
  Tools -->|yes| ToolDocs[Tool Plugins]
  Tools -->|no| Provider{Provider auth, OAuth, runtime auth, model catalog?}
  Provider -->|yes| ProviderDocs[Provider Plugins + Architecture Internals]
  Provider -->|no| Runtime{Host-owned model calls or runtime utilities?}
  Runtime -->|yes| RuntimeDocs[Runtime helpers]
  Runtime -->|no| Hooks[Host-hook examples and recipes]
  Hooks --> Workflow[Approval flows, policy gates, monitors, wizards, review assistants]

Current grouped host-hook surface covered

Pulling directly from the docs

The opening of the new page frames the work this way:

This doc is a recipe book. It does not re-document the API surface; that is the
job of Plugin SDK overview and Plugin hooks. Instead, every section here answers
a single question: if I want my plugin to do X, which host-hook contracts do I
compose, and what does that look like end-to-end?

The quick-start block then gives authors the current grouped API map:

register(api) {
  // Existing surfaces you already know:
  //   api.registerTool(...), api.registerCommand(...), api.on(...)
  //
  // Current grouped host-hook surfaces:
  //   api.session.state.registerSessionExtension(...)
  //   api.session.workflow.enqueueNextTurnInjection(...)
  //   api.session.workflow.registerSessionSchedulerJob(...)
  //   api.session.workflow.sendSessionAttachment(...)        // bundled-only
  //   api.session.workflow.scheduleSessionTurn(...)          // bundled-only
  //   api.session.workflow.unscheduleSessionTurnsByTag(...)  // bundled-only
  //   api.session.controls.registerSessionAction(...)
  //   api.session.controls.registerControlUiDescriptor(...)
  //   api.agent.events.registerAgentEventSubscription(...)
  //   api.agent.events.emitAgentEvent(...)
  //   api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
  //   api.lifecycle.registerRuntimeLifecycle(...)
}

Two important examples of source-aligned polish in this PR:

• GatewaySessionRow.pluginExtensions is described as an array of { pluginId, namespace, value } entries, not a nested object. Any nested lookup map is explicitly client-derived.
• External plugin event emission now uses plugin-id-scoped streams (pluginId or ${pluginId}.*) and calls out that host-reserved streams like lifecycle, assistant, tool, and approval are bundled-only.

How selected recipes work

Session state projection

sequenceDiagram
  autonumber
  participant Plugin
  participant Reg as Registry
  participant Store as Session Store
  participant GW as Gateway
  participant UI as Control UI

  Plugin->>Reg: registerSessionExtension({namespace, project, cleanup})
  Note over Reg,Store: namespace + pluginId now valid for sessions.pluginPatch
  UI->>GW: sessions.pluginPatch({pluginId, namespace, value})
  GW->>Reg: validate pluginId, namespace, and operator.admin scope
  Reg->>Store: write namespaced state
  Store-->>GW: { ok, key, value }
  GW-->>UI: { ok, key, value }
  GW-->>UI: sessions.changed notification
  UI->>GW: refresh session row
  GW->>Plugin: build row projection with project({sessionKey, sessionId, state})
  Plugin-->>GW: pluginExtensions[] projection entry
  GW-->>UI: refreshed row and declared slot mirror when enabled

Control UI descriptors

Control UI contributions are data-only. The plugin supplies a JSON descriptor; clients own rendering. That keeps plugin code out of client surfaces while still letting plugins expose review cards, budget meters, status panels, settings panels, and action-driven UX.

api.session.controls.registerControlUiDescriptor({
  id: "budget-meter",
  surface: "session",
  label: "Budget",
  description: "Per-session spend tracker",
  placement: "header",
  schema: {
    kind: "meter",
    source: {
      kind: "pluginExtension",
      pluginId: "budget-guard",
      namespace: "budget",
    },
    valuePath: "value.spent",
    capPath: "value.capUsd",
    format: "usd",
    warningRatio: 0.8,
    criticalRatio: 1.0,
  },
});

Session action dispatch

sequenceDiagram
  autonumber
  participant Client
  participant Gateway
  participant Registry
  participant Plugin
  participant Agent

  Client->>Gateway: plugins.sessionAction({pluginId, actionId, sessionKey, payload})
  Gateway->>Registry: find action and requiredScopes
  Gateway->>Gateway: validate caller scopes + JSON schema
  Gateway->>Plugin: handler({pluginId, actionId, sessionKey, payload, client})
  Plugin->>Gateway: { result, continueAgent }
  Gateway-->>Client: { ok:true, result, continueAgent }
  Gateway->>Agent: optional continuation path via next-turn injection

Event emission contract

The event-emission recipe was tightened after review. External plugins must use plugin-id-scoped streams:

api.agent.events.emitAgentEvent({
  runId,
  sessionKey,
  stream: "review-concierge.review",
  data: {
    phase: "summary-ready",
    filesReviewed: 12,
  },
});

That matches src/plugins/agent-event-emission.ts: external plugins cannot emit host-reserved streams and cannot emit streams owned by another plugin id.

Scope boundaries and non-goals

• Provider auth, OAuth refresh, external credential overlays, provider usage hooks, and runtime-auth hooks are intentionally routed to sdk-provider-plugins and architecture-internals; this page does not duplicate that provider catalog.
• Simple static tools are routed to tool-plugins; this page focuses on workflow-style host hooks.
• Host-owned model calls and runtime utilities are routed to sdk-runtime; this page only points authors there.
• Open/future follow-up seams such as chat-stream renderers, structured-complete helpers, or compaction interception are not documented as shipped APIs here.
• The PR does not change TypeScript declarations or runtime semantics. It is a documentation and discoverability PR over current source.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: The Plugin SDK docs now expose the current grouped host-hook APIs, correct plugin event stream scoping, and point authors toward the right adjacent docs for tool plugins, provider/OAuth hooks, and runtime helpers instead of stale companion-PR guidance.
• Real environment tested: Real OpenClaw checkout at /Volumes/LEXAR/repos/openclaw-host-hook-docs on branch docs/plugin-sdk-host-hook-recipes-split-refresh, plus GitHub Actions docs CI for commit 3465338a09.
• Exact steps or command run after this patch:

pwd
node scripts/check-docs-mdx.mjs docs/plugins/host-hooks-examples.md docs/plugins/hooks.md docs/plugins/sdk-overview.md
node scripts/format-docs.mjs --check
node scripts/check-docs-i18n-glossary.mjs
node scripts/docs-link-audit.mjs
jq empty docs/docs.json && jq empty docs/.i18n/glossary.zh-CN.json && git diff --check
gh pr checks 74853 -R openclaw/openclaw --watch --interval 10

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

$ pwd
/Volumes/LEXAR/repos/openclaw-host-hook-docs

$ node scripts/check-docs-mdx.mjs docs/plugins/host-hooks-examples.md docs/plugins/hooks.md docs/plugins/sdk-overview.md
Docs MDX check passed (3 files, 176ms).

$ node scripts/format-docs.mjs --check
Docs formatting clean (632 files).

$ node scripts/docs-link-audit.mjs
checked_internal_links=4425
broken_links=0

$ node scripts/check-docs-i18n-glossary.mjs
exited 0

• Observed result after fix: The changed docs pass MDX parsing, docs formatting, i18n glossary validation, JSON parsing, whitespace validation, and internal link audit locally. GitHub checks for commit 3465338a09 passed after the event-stream wording correction and final docs-consistency polish, including check-docs and Real behavior proof.
• What was not tested: No browser screenshot of the rendered Mintlify page was captured in this pass; this is docs-only and the repository MDX/link/i18n checks cover the changed docs surface.
• Before evidence (optional but encouraged): Earlier review identified the old event-emission example as wrong because it used plugin.review; current docs now use review-concierge.review, matching plugin-id-scoped stream policy.

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: N/A for runtime behavior. Documentation drift came from carrying an older host-hook recipe page across a fast-moving SDK stack and then rebasing it after the grouped host-hook APIs landed.
• Missing detection / guardrail: Bot review correctly caught one remaining source/doc mismatch around plugin event stream scoping; the updated page now matches emitPluginAgentEvent(...) and the contract tests.
• Contributing context (if known): The Plugin SDK moved from older flat/companion-PR language to grouped namespaces and shipped workflow seams. The PR body and docs now reflect current source instead of old stack-order assumptions.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/contracts/session-actions.contract.test.ts already covers plugin-id-scoped event emission; docs checks cover the changed Markdown/links/navigation.
• Scenario the test should lock in: workspace plugin event streams must be scoped to the plugin id or rejected; docs examples should not recommend rejected stream names.
• Why this is the smallest reliable guardrail: the behavior is already locked by the SDK contract test; the PR only needed doc alignment.
• Existing test that already covers this (if any): session-actions.contract.test.ts accepts workspace-event-plugin.workflow and rejects other-plugin.workflow for the workspace plugin.
• If no new test is added, why not: docs-only PR; no runtime behavior changed.

User-visible / Behavior Changes

Plugin authors now get a navigable recipe guide for workflow-style host hooks, linked from Plugin SDK overview, Plugin hooks, and the docs sidebar. Runtime users see no behavior change.

Diagram (if applicable)

Before:
[plugin author] -> [SDK overview table + hook catalog] -> [manual inference / stale stack context]

After:
[plugin author] -> [Host-hook examples] -> [recipe by use case]
                -> [current grouped API] -> [pitfalls + tests + cleanup semantics]

Additional system diagram:

flowchart LR
  Author[Plugin author or AI agent] --> Recipe[Host-hook recipe guide]
  Recipe --> State[Session state + projections]
  Recipe --> Workflow[Next-turn context + scheduler ownership]
  Recipe --> Controls[Actions + Control UI descriptors]
  Recipe --> Events[Agent events + run context]
  Recipe --> Cleanup[Lifecycle cleanup matrix]
  Cleanup --> Tests[Contract-test guidance]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local checkout under /Volumes/LEXAR/repos/openclaw-host-hook-docs; GitHub Actions Ubuntu runner for docs CI.
• Runtime/container: Node scripts from the existing OpenClaw repo checkout; no new install was performed.
• Model/provider: N/A
• Integration/channel (if any): GitHub PR [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853 and docs CI.
• Relevant config (redacted): N/A

Steps

1. Verify working directory is on Lexar.
2. Run focused docs MDX, formatting, i18n glossary, and link checks.
3. Inspect current source/contract tests for event-stream scoping.
4. Update PR body and comments with reviewer-facing docs excerpts and diagrams.
5. Push commit 3465338a09 and wait for PR checks.

Expected

• Docs checks pass locally and in GitHub.
• PR remains mergeable.
• Real behavior proof gate passes.
• PR body follows the repository template and contains enough architecture context for reviewers unfamiliar with the stack.

Actual

• Local docs checks passed.
• PR branch updated to 3465338a09.
• GitHub checks on 3465338a09 passed, including check-docs and Real behavior proof.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Evidence is embedded above under Real behavior proof and includes copied terminal output plus the current GitHub check-docs and Real behavior proof checks for 3465338a09.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: docs syntax, docs formatting, docs link integrity, i18n glossary coverage, JSON validity, whitespace diff check, PR template completeness, review-thread status, maintainer edit setting.
• Edge cases checked: stale companion-PR language, non-existent descriptor fields, nested pluginExtensions wording, event stream scoping, non-current API caveats, SessionEntry slot mirror wording, bundled-only helper labeling.
• What you did not verify: rendered Mintlify screenshot; full local test suite; runtime plugin execution. These were intentionally skipped because this PR is docs-only and local heavyweight suites are discouraged for this workspace.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

The latest ClawSweeper issue-comment finding about plugin.* event streams is addressed in commit 3465338a09: the recipe now uses plugin-id-scoped streams and explains the bundled-only reserved-stream exception.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: A docs recipe could drift from source and teach a non-existent or rejected SDK call.
  • Mitigation: the page now points at the current contract test files, uses grouped APIs from src/plugins/types.ts, and was checked against the event-emission source/contract test after bot review.
• Risk: The page could blur boundaries between workflow hooks, provider/OAuth hooks, static tool plugins, and runtime helpers.
  • Mitigation: the quick-start and related links explicitly route provider auth/OAuth to provider docs, static tools to Tool Plugins, and host-owned model calls to Runtime helpers.
• Risk: The docs-only branch could be mistaken for a runtime SDK change.
  • Mitigation: the PR body marks this as docs-only, all security-impact answers are No, and the changed-file list is limited to docs/nav/glossary.