**Subagents**

- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` - coordinate subagent routing and completion delivery

- `subagent_spawned` / `subagent_ended` - observe subagent launch and completion.

- `subagent_delivery_target` - compatibility hook for completion delivery when no core session binding can project a route.

- `subagent_spawning` - deprecated compatibility hook. Core now prepares `thread: true` subagent bindings through channel session-binding adapters before `subagent_spawned` fires.

- `subagent_spawned` includes `resolvedModel` and `resolvedProvider` when OpenClaw has resolved the child session's native model before launch.

**Lifecycle**

- **`before_agent_start`** remains for compatibility. New plugins should use

`before_model_resolve` and `before_prompt_build` instead of the combined

phase.

- **`subagent_spawning`** remains for compatibility with older plugins, but

new plugins should not return thread routing from it. Core prepares

`thread: true` subagent bindings through channel session-binding adapters

before `subagent_spawned` fires.

- **`deactivate`** remains as a deprecated cleanup compatibility alias until

after 2026-08-16. New plugins should use `gateway_stop`.

- **`onResolution` in `before_tool_call`** now uses the typed

</Accordion>

<Accordion title="subagent_spawning hook → core thread binding">

**Old**: `api.on("subagent_spawning", handler)` returning

`threadBindingReady` or `deliveryOrigin`.

**New**: let core prepare `thread: true` subagent bindings through the

channel session-binding adapter. Use `api.on("subagent_spawned", handler)`

only for post-launch observation.

```typescript

// Before

api.on("subagent_spawning", async () => ({

status: "ok",

threadBindingReady: true,

deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },

}));

// After

api.on("subagent_spawned", async (event) => {

await observeSubagentLaunch(event);

});

```

`subagent_spawning`, `PluginHookSubagentSpawningEvent`,

`PluginHookSubagentSpawningResult`, and

`SubagentLifecycleHookRunner.runSubagentSpawning(...)` remain only as

deprecated compatibility surfaces while external plugins migrate.

</Accordion>

<Accordion title="Provider discovery types → provider catalog types">

Four discovery type aliases are now thin wrappers over the

catalog-era types:

### Thread supporting channels

**Discord** is currently the only supported channel. It supports

persistent thread-bound subagent sessions (`sessions_spawn` with

`thread: true`), manual thread controls (`/focus`, `/unfocus`, `/agents`,

`/session idle`, `/session max-age`), and adapter keys

`channels.discord.threadBindings.enabled`,

`channels.discord.threadBindings.idleHours`,

`channels.discord.threadBindings.maxAgeHours`, and

`channels.discord.threadBindings.spawnSessions`.

Any channel with a session-binding adapter can support persistent

thread-bound subagent sessions (`sessions_spawn` with `thread: true`).

Bundled adapters currently include Discord threads, Matrix threads,

Telegram forum topics, and current-conversation bindings for Feishu.

Use the per-channel `threadBindings` config keys for enablement,

timeouts, and `spawnSessions`.

### Quick flow

} from "openclaw/plugin-sdk/channel-test-helpers";

import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";

import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";

import { handleDiscordSubagentSpawning } from "./subagent-hooks.js";

type ThreadBindingRecord = {

accountId: string;

) {

return registerHookHandlersForTest<OpenClawPluginApi>({

config,

register: registerDiscordSubagentHooks,

register: (api) => {

registerDiscordSubagentHooks(api);

api.on("subagent_spawning", (event) => handleDiscordSubagentSpawning(api, event));

},

});

}

// Subagent hooks live behind a dedicated barrel so the bundled entry can

// register one stable hook wiring path while keeping the handler module lazy.

export function registerDiscordSubagentHooks(api: OpenClawPluginApi): void {

api.on("subagent_spawning", async (event) => {

const { handleDiscordSubagentSpawning } = await loadDiscordSubagentHooksModule();

return await handleDiscordSubagentSpawning(api, event);

});

api.on("subagent_ended", async (event) => {

const { handleDiscordSubagentEnded } = await loadDiscordSubagentHooksModule();

handleDiscordSubagentEnded(event);

import { beforeEach, describe, expect, it } from "vitest";

import type { ClawdbotConfig, OpenClawPluginApi } from "../runtime-api.js";

import { registerFeishuSubagentHooks } from "../subagent-hooks-api.js";

import { handleFeishuSubagentSpawning } from "./subagent-hooks.js";

import {

createFeishuThreadBindingManager,

testing as threadBindingTesting,

function registerHandlersForTest(config: Record<string, unknown> = baseConfig) {

return registerHookHandlersForTest<OpenClawPluginApi>({

config,

register: registerFeishuSubagentHooks,

register: (api) => {

registerFeishuSubagentHooks(api);

api.on("subagent_spawning", (event, ctx) => handleFeishuSubagentSpawning(event, ctx));

},

});

}

}

export function registerFeishuSubagentHooks(api: OpenClawPluginApi): void {

api.on("subagent_spawning", async (event, ctx) => {

const { handleFeishuSubagentSpawning } = await loadFeishuSubagentHooksModule();

return await handleFeishuSubagentSpawning(event, ctx);

});

api.on("subagent_delivery_target", async (event) => {

const { handleFeishuSubagentDeliveryTarget } = await loadFeishuSubagentHooksModule();

return handleFeishuSubagentDeliveryTarget(event);

expect(runtimeMocks.ensureMatrixCryptoRuntime).not.toHaveBeenCalled();

expect(on.mock.calls.map(([hookName]) => hookName)).toEqual([

"subagent_spawning",

"subagent_ended",

"subagent_delivery_target",

]);

const handlers = Object.fromEntries(on.mock.calls);

await expect(handlers.subagent_spawning({ id: "spawn" })).resolves.toBe("spawned");

await expect(handlers.subagent_ended({ id: "ended" })).resolves.toBeUndefined();

await expect(handlers.subagent_delivery_target({ id: "target" })).resolves.toBe(

"delivery-target",

);

expect(runtimeMocks.handleMatrixSubagentSpawning).toHaveBeenCalledWith(api, { id: "spawn" });

expect(runtimeMocks.handleMatrixSubagentEnded).toHaveBeenCalledWith({ id: "ended" });

expect(runtimeMocks.handleMatrixSubagentDeliveryTarget).toHaveBeenCalledWith({ id: "target" });

});

function registerHandlersForTest(config: Record<string, unknown> = {}) {

return registerHookHandlersForTest<MatrixEntryPluginApi>({

config,

register: registerMatrixSubagentHooks,

register: (api) => {

registerMatrixSubagentHooks(api);

api.on("subagent_spawning", (event) => handleMatrixSubagentSpawning(api, event));

},

});

}

}

export function registerMatrixSubagentHooks(api: OpenClawPluginApi): void {

api.on("subagent_spawning", async (event) => {

const { handleMatrixSubagentSpawning } = await loadMatrixSubagentHooksModule();

return await handleMatrixSubagentSpawning(api, event);

});

api.on("subagent_ended", async (event) => {

const { handleMatrixSubagentEnded } = await loadMatrixSubagentHooksModule();

await handleMatrixSubagentEnded(event);