> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin hooks reference

> Exhaustive reference for the 35 plugin lifecycle hooks: registration, contexts, per-hook event and result types, mutation semantics, and timeouts.

# Plugin hooks reference

This is the exhaustive contract reference for WednesdayAI's **plugin lifecycle hooks** — the typed events registered inside a plugin with `api.on(name, handler, opts?)`. Source of truth: `PluginHookName`, `PluginHookHandlerMap`, and the `PluginHook*` types in `src/plugins/types.ts`, re-exported from `openclaw/plugin-sdk`.

For the authoring guide (which hook to pick, mutation categories, examples) see [Hooks](https://docs.wednesdayai.dev/next/developers/hooks.md). For standalone `HOOK.md` hooks and the bundled hook catalogue, see [Hooks catalogue](https://docs.wednesdayai.dev/next/reference/hooks-catalogue.md) — those are a different system.

## Registration

```typescript theme={"dark"}
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";

export default function register(api: OpenClawPluginApi): void {
  api.on("before_tool_call", (event, ctx) => {
    // event and ctx are statically typed per hook name
    return { block: true, blockReason: "not allowed after hours" };
  }, { priority: 10 });   // optional; higher runs later within a hook
}
```

* Handlers may be synchronous or `async`; the runtime awaits them.
* Handlers for the same hook run **sequentially** in registration order; `{ priority }` orders across plugins.
* **Context lifecycle hooks** (`context.collect`, `context.project`, `context.prune`, `compaction.plan`) are awaited with a **5 000 ms timeout**; a timed-out handler is logged and skipped. Other hooks have no dedicated timeout but sit on the run's critical path — keep them fast.
* A thrown handler error is caught and logged per `catchErrors` policy; it does not crash the gateway.

## Shared context types

Most hooks receive one of these as the second (`ctx`) argument:

```typescript theme={"dark"}
// Agent context — model/prompt/tool/session/gateway hooks
type PluginHookAgentContext = {
  agentId?: string; sessionKey?: string; sessionId?: string; runId?: string;
  workspaceDir?: string; messageProvider?: string;
  trigger?: string;            // "user" | "heartbeat" | "cron" | "steer" | "memory" | "internal"
  channelId?: string; workspaceLane?: WorkspaceLaneResolution;
  channelContext?: PluginHookChannelContext;  // { channelId, senderExternalId?, channelConversationId?, [key: string]: unknown }
  runtimeIdentity?: PluginRuntimeIdentity;    // resolved identity — see below
  turn?: PluginTurnIdentity;                  // turn correlation — see below
} & SenderIdentityFields;

// Message context — message_* hooks
type PluginHookMessageContext = {
  channelId: string; accountId?: string;
  conversationId?: string;      // legacy alias of channelConversationId
  channelConversationId?: string; messageProvider?: string;
  sessionId?: string; sessionKey?: string; runId?: string; messageId?: string;
  senderId?: string; senderName?: string; senderUsername?: string; senderE164?: string;
  canonicalIdentity?: string; senderIsOwner?: boolean; laneId?: string;
  workspaceLane?: WorkspaceLaneResolution;
  channelContext?: PluginHookChannelContext;
  runtimeIdentity?: PluginRuntimeIdentity; turn?: PluginTurnIdentity;
};

// Tool context — before/after_tool_call
type PluginHookToolContext = {
  agentId?: string; sessionKey?: string;
  sessionId?: string;           // ephemeral session UUID — regenerated on /new and /reset
  runId?: string; toolName: string; toolCallId?: string;
  runtimeIdentity?: PluginRuntimeIdentity; turn?: PluginTurnIdentity;
};

// Context lifecycle — storage.afterAppend, context.*, compaction.plan
// See ContextLifecycleContext in /developers/context-engine.
```

`PluginRuntimeIdentity` carries resolved identity: `agentId`/`agentName`, `sessionId`/`sessionKey`, `channelConversationId`, opaque `providerConversationId` + `hashedUserId`, raw sender fields (`senderId`/`senderName`/`senderUsername`/`senderE164`), `canonicalIdentity` + `identitySource` (`"sender" | "parent-session" | "job-config"`), `senderIsOwner`, `messageProvider`, `channelId`, and `laneId` (opaque workspace-lane digest). `PluginTurnIdentity` carries `turnId` (equals `runId`), sequence numbers (`userSeq`/`assistantSeq`, global variants), and entry ids.

## Hook catalogue

### Model and prompt hooks

| Hook | Fires | Event shape (abridged) | Return |
| - | - | - | - |
| `before_model_resolve` | Before the model/provider is chosen | `{ prompt: string }` | `{ modelOverride?, providerOverride? }` |
| `before_prompt_build` | Before system prompt + context assembly | `{ prompt, messages: unknown[], systemPrompt?: string }` | `{ systemPrompt?, prependContext? }` — `systemPrompt` appended after built sections; `prependContext` inserted before the user turn |
| `before_context_send` | Just before messages go to the model | `{ messages: AgentMessage[], modelId, provider, contextWindowTokens }` | `{ messages? }` replaces the outgoing list |
| `before_agent_start` | Legacy combined pre-run hook | `{ prompt, messages?: unknown[] }` | combines prompt-build + model-resolve results |
| `llm_input` | After input is prepared | `{ runId, sessionId, provider, model, systemPrompt?, prompt, historyMessages, imagesCount }` | void (observe) |
| `llm_output` | After the model returns | `{ runId, sessionId, provider, model, assistantTexts, lastAssistant?, usage? }` | void (observe) |
| `model_call_ended` | Once per run attempt, after the full tool-use loop | `{ runId, callId, provider, model, durationMs, outcome: "completed" \| "error", failureKind?, timeToFirstByteMs?, usage?, responseHeaders?, proxyMetadata? }` | void — but may **mutate `usage` / `proxyMetadata` in place** (core reads `proxyMetadata` back for actualProvider/actualModel); runs serially |
| `agent_end` | Agent run finishes | `{ messages: unknown[], success, error?, durationMs? }` | void (observe) |

> [!NOTE]
>
> `model_call_ended` fires per *attempt*, not per individual LLM API call inside a
> tool-use loop. Use `llm_output` for a stable post-run observation point.

### Message hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `message_received` | Inbound message received (session ids may be absent — never fabricated) | `{ from, content, timestamp?, metadata? }` on `PluginHookMessageContext` | void (observe) |
| `message_sending` | Before an outbound message is sent | `{ to, content, metadata? }` | `{ content?, cancel? }` — rewrite or cancel |
| `message_sent` | After delivery (success or failure) | `{ to, content, success, error? }` | void (observe) |

### Tool hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `before_tool_call` | Before a tool executes | `{ toolName, params, runId?, toolCallId? }` | `{ params?, block?, blockReason? }` — rewrite params or short-circuit |
| `after_tool_call` | After a tool executes | `{ toolName, params, runId?, toolCallId?, result?, error?, durationMs? }` | void (observe) |
| `tool_result_persist` | Before a tool result is written to the transcript | `{ toolName?, toolCallId?, message: AgentMessage, isSynthetic? }` | `{ message? }` replaces the persisted message |
| `before_message_write` | Before any message is written to the transcript | `{ message, sessionKey?, agentId? }` | `{ block?, message? }` — block the write or replace the message |

### Session hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `session_start` | A session starts | `{ sessionId, sessionKey?, resumedFrom? }` | void (observe) |
| `session_end` | A session ends | `{ sessionId, sessionKey?, messageCount, durationMs? }` | void (observe) |
| `before_reset` | On `/new` / `/reset`, before the session clears | `{ sessionFile?, messages?, reason? }` | void (observe) |

### Subagent hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `subagent_spawning` | Before a subagent spawn | `{ childSessionKey, agentId, label?, mode: "run" \| "session", requester?, threadRequested }` | `{ status: "ok", threadBindingReady? }` to allow, or `{ status: "error", error }` to block |
| `subagent_delivery_target` | Resolving where a subagent reply is delivered | `{ childSessionKey, requesterSessionKey, requesterOrigin?, childRunId?, spawnMode?, expectsCompletionMessage }` | `{ origin? }` overrides the delivery origin |
| `subagent_spawned` | A subagent has spawned | spawn base + `{ runId }` | void (observe) |
| `subagent_ended` | A subagent ended | `{ targetSessionKey, targetKind: "subagent" \| "acp", reason, sendFarewell?, accountId?, runId?, endedAt?, outcome?, error? }` | void (observe) |

Subagent hooks receive `PluginHookSubagentContext`: `{ runId?, childSessionKey?, requesterSessionKey?, runtimeIdentity?, turn? }`.

### Gateway hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `gateway_start` | Gateway process starts | `{ port: number }` | void (observe) |
| `gateway_stop` | Gateway process stops | `{ reason? }` | void (observe) |

### Transform hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `transform_llm_input` | Mutate the message list before the model call | `{ messages: AgentMessage[], provider, model }` | `{ messages }` — replaces the input |
| `transform_llm_output` | Mutate assistant output after the model call | `{ assistantTexts: string[], lastAssistant?, provider, model }` | `{ assistantTexts? }` |

### Storage and context lifecycle hooks

All receive `ContextLifecycleContext` (see [Context engine](https://docs.wednesdayai.dev/next/developers/context-engine.md)). These are the context-engine surface:

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `storage.afterAppend` | After a conversation entry is appended to storage | `{ entry: StoredConversationEntry, cursor: StorageCursor }` | void (observe) |
| `context.collect` | Collecting context for the current turn | `{ prompt, cleanUserMessage, messages, envelope, storage? }` | `PromptContribution` — merged by placement, priority-sorted |
| `context.project` | Projecting contributions into messages | `{ messages, contributions, envelope, storage? }` | `{ messages?, projection?, contribution? }` |
| `context.prune` | Pruning under token pressure | `{ messages, tokenWindow?, usage?, storage? }` | `{ messages?, dropped?, contribution?, compactionHandled? }` |
| `compaction.plan` | Planning a compaction pass | `{ messages, tokenWindow?, usage?, storageCursor? }` | `{ plan?, messages?, contribution? }` |

### Compaction observer hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `before_compaction` | Before compaction runs | `{ messageCount, compactingCount?, tokenCount?, messages?, sessionFile? }` — all pre-compaction messages are already on disk | void (observe) |
| `after_compaction` | After compaction completes | `{ messageCount, tokenCount?, compactedCount, sessionFile? }` | void (observe) |

### Scheduling and outcome hooks

| Hook | Fires | Event shape | Return |
| - | - | - | - |
| `agent_idle` | Core idle monitor crosses an idle threshold or a schedule window opens (ADR 0048) | `{ agentId, idleSinceMs, idleForMs, trigger: "idle" \| "schedule" }` | void (observe) |
| `task_outcome` | Task/subagent completion outcome emitted (ADR 0048) | `{ taskRunId?, agentId?, source: "task" \| "subagent" \| "session", outcome: "completed" \| "failed" \| "preempted" \| "cancelled", quality?, meta? }` — `"session"` source is reserved and not yet produced; handlers must treat it as reachable | void (observe) |

## What not to do

```typescript theme={"dark"}
// ❌ import { HookContext } from "openclaw/plugin-sdk";  — does not exist
// ❌ return value from an observe-only hook (llm_output, agent_end, ...) — ignored
// ❌ slow context.* handler — abandoned after 5000 ms, contribution lost
// ❌ mutating event.messages in place — return a new value instead
```

## Related

* [Hooks](https://docs.wednesdayai.dev/next/developers/hooks.md) — authoring guide and mutation categories
* [Context engine](https://docs.wednesdayai.dev/next/developers/context-engine.md) — the `context.*` / `compaction.plan` pipeline in depth
* [Hooks catalogue](https://docs.wednesdayai.dev/next/reference/hooks-catalogue.md) — standalone `HOOK.md` hooks and bundled hooks (a separate system)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.