read_when:

- You see the OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED warning

- You see the OPENCLAW_EXTENSION_API_DEPRECATED warning

- You use api.registerEmbeddedExtensionFactory

- You used api.registerEmbeddedExtensionFactory before OpenClaw 2026.4.24

- You are updating a plugin to the modern plugin architecture

- You maintain an external OpenClaw plugin

---

new plugin architecture was being built.

- **`openclaw/extension-api`** — a bridge that gave plugins direct access to

host-side helpers like the embedded agent runner.

- **`api.registerEmbeddedExtensionFactory(...)`** — a Pi-only bundled extension

hook that could observe embedded-runner events such as `tool_result`.

- **`api.registerEmbeddedExtensionFactory(...)`** — a removed Pi-only bundled

extension hook that could observe embedded-runner events such as

`tool_result`.

These surfaces are now **deprecated**. They still work at runtime, but new

plugins must not use them, and existing plugins should migrate before the next

major release removes them.

The broad import surfaces are now **deprecated**. They still work at runtime,

but new plugins must not use them, and existing plugins should migrate before

the next major release removes them. The Pi-only embedded extension factory

registration API has been removed; use tool-result middleware instead.

OpenClaw does not remove or reinterpret documented plugin behavior in the same

change that introduces a replacement. Breaking contract changes must first go

<Warning>

The backwards-compatibility layer will be removed in a future major release.

Plugins that still import from these surfaces will break when that happens.

Pi-only embedded extension factory registrations already no longer load.

</Warning>

## Why this changed

<Steps>

<Step title="Migrate Pi tool-result extensions to middleware">

Bundled plugins should replace Pi-only

Bundled plugins must replace Pi-only

`api.registerEmbeddedExtensionFactory(...)` tool-result handlers with

runtime-neutral middleware.

```typescript

// Before: Pi-only compatibility hook

api.registerEmbeddedExtensionFactory((pi) => {

pi.on("tool_result", async (event) => {

return compactToolResult(event);

});

});

// After: Pi and Codex runtime dynamic tools

// Pi and Codex runtime dynamic tools

api.registerAgentToolResultMiddleware(async (event) => {

return compactToolResult(event);

}, {

}

```

Keep `contracts.embeddedExtensionFactories` only for bundled compatibility

code that still needs direct Pi embedded-runner events. External plugins

cannot register tool-result middleware because it can rewrite high-trust

tool output before the model sees it.

External plugins cannot register tool-result middleware because it can

rewrite high-trust tool output before the model sees it.

</Step>

<Accordion title="Embedded extension factories → agent tool-result middleware">

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

middleware" above. Included here for completeness: the removed Pi-only

`api.registerEmbeddedExtensionFactory(...)` path is replaced by

`api.registerAgentToolResultMiddleware(...)` with an explicit runtime

list in `contracts.agentToolResultMiddleware`.

</Accordion>