diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md
index a8cfe86e0b5..48a9aaa8a54 100644
--- a/docs/plugins/hooks.md
+++ b/docs/plugins/hooks.md
@@ -223,8 +223,30 @@ resources.
Do not rely on the internal `gateway:startup` hook for plugin-owned runtime
services.
+## Upcoming deprecations
+
+A few hook-adjacent surfaces are deprecated but still supported. Migrate
+before the next major release:
+
+- **Plaintext channel envelopes** in `inbound_claim` and `message_received`
+ handlers. Read `BodyForAgent` and the structured user-context blocks
+ instead of parsing flat envelope text. See
+ [Plaintext channel envelopes → BodyForAgent](/plugins/sdk-migration#active-deprecations).
+- **`before_agent_start`** remains for compatibility. New plugins should use
+ `before_model_resolve` and `before_prompt_build` instead of the combined
+ phase.
+- **`onResolution` in `before_tool_call`** now uses the typed
+ `PluginApprovalResolution` union (`allow-once` / `allow-always` / `deny` /
+ `timeout` / `cancelled`) instead of a free-form `string`.
+
+For the full list — memory capability registration, provider thinking
+profile, external auth providers, provider discovery types, task runtime
+accessors, and the `command-auth` → `command-status` rename — see
+[Plugin SDK migration → Active deprecations](/plugins/sdk-migration#active-deprecations).
+
## Related
+- [Plugin SDK migration](/plugins/sdk-migration) — active deprecations and removal timeline
- [Building plugins](/plugins/building-plugins)
- [Plugin SDK overview](/plugins/sdk-overview)
- [Plugin entry points](/plugins/sdk-entrypoints)
diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md
index 36eb486e33a..97800589d11 100644
--- a/docs/plugins/sdk-migration.md
+++ b/docs/plugins/sdk-migration.md
@@ -432,6 +432,223 @@ surface `DEFAULT_COPILOT_API_BASE_URL`,
Use the narrowest import that matches the job. If you cannot find an export,
check the source at `src/plugin-sdk/` or ask in Discord.
+## Active deprecations
+
+Narrower deprecations that apply across the plugin SDK, provider contract,
+runtime surface, and manifest. Each one still works today but will be removed
+in a future major release. The entry below every item maps the old API to its
+canonical replacement.
+
+
+
+ **Old (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`,
+ `buildCommandsMessagePaginated`, `buildHelpMessage`.
+
+ **New (`openclaw/plugin-sdk/command-status`)**: same signatures, same
+ exports — just imported from the narrower subpath. `command-auth`
+ re-exports them as compat stubs.
+
+ ```typescript
+ // Before
+ import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";
+
+ // After
+ import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";
+ ```
+
+
+
+
+ **Old**: `resolveInboundMentionRequirement({ facts, policy })` and
+ `shouldDropInboundForMention(...)` from
+ `openclaw/plugin-sdk/channel-inbound` or
+ `openclaw/plugin-sdk/channel-mention-gating`.
+
+ **New**: `resolveInboundMentionDecision({ facts, policy })` — returns a
+ single decision object instead of two split calls.
+
+ Downstream channel plugins (Slack, Discord, Matrix, MS Teams) have already
+ switched.
+
+
+
+
+ `openclaw/plugin-sdk/channel-runtime` is a compatibility shim for older
+ channel plugins. Do not import it from new code; use
+ `openclaw/plugin-sdk/channel-runtime-context` for registering runtime
+ objects.
+
+ `channelActions*` helpers in `openclaw/plugin-sdk/channel-actions` are
+ deprecated alongside raw "actions" channel exports. Expose capabilities
+ through the semantic `presentation` surface instead — channel plugins
+ declare what they render (cards, buttons, selects) rather than which raw
+ action names they accept.
+
+
+
+
+ **Old**: `tool()` factory from `openclaw/plugin-sdk/provider-web-search`.
+
+ **New**: implement `createTool(...)` directly on the provider plugin.
+ OpenClaw no longer needs the SDK helper to register the tool wrapper.
+
+
+
+
+ **Old**: `formatInboundEnvelope(...)` (and
+ `ChannelMessageForAgent.channelEnvelope`) to build a flat plaintext prompt
+ envelope from inbound channel messages.
+
+ **New**: `BodyForAgent` plus structured user-context blocks. Channel
+ plugins attach routing metadata (thread, topic, reply-to, reactions) as
+ typed fields instead of concatenating them into a prompt string. The
+ `formatAgentEnvelope(...)` helper is still supported for synthesized
+ assistant-facing envelopes, but inbound plaintext envelopes are on the
+ way out.
+
+ Affected areas: `inbound_claim`, `message_received`, and any custom
+ channel plugin that post-processed `channelEnvelope` text.
+
+
+
+
+ Four discovery type aliases are now thin wrappers over the
+ catalog-era types:
+
+ | Old alias | New type |
+ | ------------------------- | ------------------------- |
+ | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
+ | `ProviderDiscoveryContext`| `ProviderCatalogContext` |
+ | `ProviderDiscoveryResult` | `ProviderCatalogResult` |
+ | `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
+
+ Plus the legacy `ProviderCapabilities` static bag — provider plugins
+ should attach capability facts through the provider runtime contract
+ rather than a static object.
+
+
+
+
+ **Old** (three separate hooks on `ProviderThinkingPolicy`):
+ `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)`, and
+ `resolveDefaultThinkingLevel(ctx)`.
+
+ **New**: a single `resolveThinkingProfile(ctx)` that returns a
+ `ProviderThinkingProfile` with the canonical `id`, optional `label`, and
+ ranked level list. OpenClaw downgrades stale stored values by profile
+ rank automatically.
+
+ Implement one hook instead of three. The legacy hooks keep working during
+ the deprecation window but are not composed with the profile result.
+
+
+
+
+ **Old**: implementing `resolveExternalOAuthProfiles(...)` without
+ declaring the provider in the plugin manifest.
+
+ **New**: declare `contracts.externalAuthProviders` in the plugin manifest
+ **and** implement `resolveExternalAuthProfiles(...)`. The old "auth
+ fallback" path emits a warning at runtime and will be removed.
+
+ ```json
+ {
+ "contracts": {
+ "externalAuthProviders": ["anthropic", "openai"]
+ }
+ }
+ ```
+
+
+
+
+ **Old** manifest field: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`.
+
+ **New**: mirror the same env-var lookup into `setup.providers[].envVars`
+ on the manifest. This consolidates setup/status env metadata in one
+ place and avoids booting the plugin runtime just to answer env-var
+ lookups.
+
+ `providerAuthEnvVars` remains supported through a compatibility adapter
+ until the deprecation window closes.
+
+
+
+
+ **Old**: three separate calls —
+ `api.registerMemoryPromptSection(...)`,
+ `api.registerMemoryFlushPlan(...)`,
+ `api.registerMemoryRuntime(...)`.
+
+ **New**: one call on the memory-state API —
+ `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`.
+
+ Same slots, single registration call. Additive memory helpers
+ (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`,
+ `registerMemoryEmbeddingProvider`) are not affected.
+
+
+
+
+ Two legacy type aliases still exported from `src/plugins/runtime/types.ts`:
+
+ | Old | New |
+ | ----------------------------- | ------------------------------- |
+ | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
+ | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
+
+ The runtime method `readSession` is deprecated in favor of
+ `getSessionMessages`. Same signature; the old method calls through to the
+ new one.
+
+
+
+
+ **Old**: `runtime.tasks.flow` (singular) returned a live task-flow accessor.
+
+ **New**: `runtime.tasks.flows` (plural) returns DTO-based TaskFlow access,
+ which is import-safe and does not require the full task runtime to be
+ loaded.
+
+ ```typescript
+ // Before
+ const flow = api.runtime.tasks.flow(ctx);
+ // After
+ const flows = api.runtime.tasks.flows(ctx);
+ ```
+
+
+
+
+ Covered in "How to migrate → Migrate Pi tool-result extensions to
+ middleware" above. Included here for completeness: the Pi-only
+ `api.registerEmbeddedExtensionFactory(...)` path is deprecated in favor of
+ `api.registerAgentToolResultMiddleware(...)` with an explicit harness
+ list in `contracts.agentToolResultMiddleware`.
+
+
+
+ `OpenClawSchemaType` re-exported from `openclaw/plugin-sdk` is now a
+ one-line alias for `OpenClawConfig`. Prefer the canonical name.
+
+ ```typescript
+ // Before
+ import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
+ // After
+ import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
+ ```
+
+
+
+
+
+Extension-level deprecations (inside bundled channel/provider plugins under
+`extensions/`) are tracked inside their own `api.ts` and `runtime-api.ts`
+barrels. They do not affect third-party plugin contracts and are not listed
+here. If you consume a bundled plugin's local barrel directly, read the
+deprecation comments in that barrel before upgrading.
+
+
## Removal timeline
| When | What happens |