mirror of https://github.com/openclaw/openclaw.git
docs: add complete plugin hook reference and fix context fields in hooks.md
- Add reference table for all 27 plugin hook names with execution model and return types - Fix agent:bootstrap context: add missing sessionKey, sessionId, agentId fields - Fix session patch context: add fastMode, spawnedWorkspaceDir, subagentRole, subagentControlScope - Fix responseUsage: add backwards-compat "on" value - Add session:compact:before and session:compact:after payload field documentation - Remove internal PR reference (#20800) - Fix handler file resolution: document handler.js and index.js fallbacks
This commit is contained in:
Vincent Koc
parent
cb428aca1c
commit
89f9433fbf
|
|
@ -129,7 +129,7 @@ Example `package.json`:
|
|||
}
|
||||
```
|
||||
|
||||
Each entry points to a hook directory containing `HOOK.md` and `handler.ts` (or `index.ts`).
|
||||
Each entry points to a hook directory containing `HOOK.md` and a handler file. The loader tries `handler.ts`, `handler.js`, `index.ts`, `index.js` in order.
|
||||
Hook packs can ship dependencies; they will be installed under `~/.openclaw/hooks/<id>`.
|
||||
Each `openclaw.hooks` entry must stay inside the package directory after symlink
|
||||
resolution; entries that escape are rejected.
|
||||
|
|
@ -236,6 +236,9 @@ Each event includes:
|
|||
sessionId?: string,
|
||||
// Agent bootstrap events (agent:bootstrap):
|
||||
bootstrapFiles?: WorkspaceBootstrapFile[],
|
||||
sessionKey?: string, // routing session key
|
||||
sessionId?: string, // internal session UUID
|
||||
agentId?: string, // resolved agent ID
|
||||
// Message events (see Message Events section for full details):
|
||||
from?: string, // message:received
|
||||
to?: string, // message:sent
|
||||
|
|
@ -265,6 +268,25 @@ Triggered when agent commands are issued:
|
|||
Internal hook payloads emit these as `type: "session"` with `action: "compact:before"` / `action: "compact:after"`; listeners subscribe with the combined keys above.
|
||||
Specific handler registration uses the literal key format `${type}:${action}`. For these events, register `session:compact:before` and `session:compact:after`.
|
||||
|
||||
`session:compact:before` context fields:
|
||||
|
||||
- `sessionId`: internal session UUID
|
||||
- `missingSessionKey`: true when no session key was available
|
||||
- `messageCount`: number of messages before compaction
|
||||
- `tokenCount`: token count before compaction (may be absent)
|
||||
- `messageCountOriginal`: message count from the full untruncated session history
|
||||
- `tokenCountOriginal`: token count of the full original history (may be absent)
|
||||
|
||||
`session:compact:after` context fields (in addition to `sessionId` and `missingSessionKey`):
|
||||
|
||||
- `messageCount`: message count after compaction
|
||||
- `tokenCount`: token count after compaction (may be absent)
|
||||
- `compactedCount`: number of messages that were compacted/removed
|
||||
- `summaryLength`: character length of the generated compaction summary
|
||||
- `tokensBefore`: token count from before compaction (for delta calculation)
|
||||
- `tokensAfter`: token count after compaction
|
||||
- `firstKeptEntryId`: ID of the first message entry retained after compaction
|
||||
|
||||
### Agent Events
|
||||
|
||||
- **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)
|
||||
|
|
@ -298,7 +320,11 @@ Session events include rich context about the session and changes:
|
|||
verboseLevel?: string | null, // Verbose output level
|
||||
reasoningLevel?: string | null, // Reasoning mode override
|
||||
elevatedLevel?: string | null, // Elevated mode override
|
||||
responseUsage?: "off" | "tokens" | "full" | null, // Usage display mode
|
||||
responseUsage?: "off" | "tokens" | "full" | "on" | null, // Usage display mode ("on" is backwards-compat alias for "full")
|
||||
fastMode?: boolean | null, // Fast/turbo mode toggle
|
||||
spawnedWorkspaceDir?: string | null, // Workspace dir override for spawned subagents
|
||||
subagentRole?: "orchestrator" | "leaf" | null, // Subagent role assignment
|
||||
subagentControlScope?: "children" | "none" | null, // Scope of subagent control
|
||||
|
||||
// Tool execution settings
|
||||
execHost?: string | null, // Exec host (sandbox|gateway|node)
|
||||
|
|
@ -318,7 +344,7 @@ Session events include rich context about the session and changes:
|
|||
}
|
||||
```
|
||||
|
||||
**Security note:** Only privileged clients (including the Control UI) can trigger `session:patch` events. Standard WebChat clients are blocked from patching sessions (see PR #20800), so the hook will not fire from those connections.
|
||||
**Security note:** Only privileged clients (including the Control UI) can trigger `session:patch` events. Standard WebChat clients are blocked from patching sessions, so the hook will not fire from those connections.
|
||||
|
||||
See `SessionsPatchParamsSchema` in `src/gateway/protocol/schema/sessions.ts` for the complete type definition.
|
||||
|
||||
|
|
@ -574,6 +600,83 @@ Compaction lifecycle hooks exposed through the plugin hook runner:
|
|||
- **`before_compaction`**: Runs before compaction with count/token metadata
|
||||
- **`after_compaction`**: Runs after compaction with compaction summary metadata
|
||||
|
||||
### Complete Plugin Hook Reference
|
||||
|
||||
All 27 hooks registered via the Plugin SDK. Hooks marked **sequential** run in priority order and can modify results; **parallel** hooks are fire-and-forget.
|
||||
|
||||
#### Model and prompt hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `before_model_resolve` | Before model/provider lookup | Sequential | `{ modelOverride?, providerOverride? }` |
|
||||
| `before_prompt_build` | After model resolved, session messages ready | Sequential | `{ systemPrompt?, prependContext?, appendSystemContext? }` |
|
||||
| `before_agent_start` | Legacy combined hook (prefer the two above) | Sequential | Union of both result shapes |
|
||||
| `llm_input` | Immediately before the LLM API call | Parallel | `void` |
|
||||
| `llm_output` | Immediately after LLM response received | Parallel | `void` |
|
||||
|
||||
#### Agent lifecycle hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `agent_end` | After agent run completes (success or failure) | Parallel | `void` |
|
||||
| `before_reset` | When `/new` or `/reset` clears a session | Parallel | `void` |
|
||||
| `before_compaction` | Before compaction summarizes history | Parallel | `void` |
|
||||
| `after_compaction` | After compaction completes | Parallel | `void` |
|
||||
|
||||
#### Session lifecycle hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `session_start` | When a new session begins | Parallel | `void` |
|
||||
| `session_end` | When a session ends | Parallel | `void` |
|
||||
|
||||
#### Message flow hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `inbound_claim` | Before command/agent dispatch; first-claim wins | Sequential | `{ handled: boolean }` |
|
||||
| `message_received` | After an inbound message is received | Parallel | `void` |
|
||||
| `before_dispatch` | After commands parsed, before model dispatch | Sequential | `{ handled: boolean, text? }` |
|
||||
| `message_sending` | Before an outbound message is delivered | Sequential | `{ content?, cancel? }` |
|
||||
| `message_sent` | After an outbound message is delivered | Parallel | `void` |
|
||||
| `before_message_write` | Before a message is written to session transcript | **Sync**, sequential | `{ block?, message? }` |
|
||||
|
||||
#### Tool execution hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `before_tool_call` | Before each tool call | Sequential | `{ params?, block?, blockReason?, requireApproval? }` |
|
||||
| `after_tool_call` | After a tool call completes | Parallel | `void` |
|
||||
| `tool_result_persist` | Before a tool result is written to transcript | **Sync**, sequential | `{ message? }` |
|
||||
|
||||
#### Subagent hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `subagent_spawning` | Before a subagent session is created | Sequential | `{ status, threadBindingReady? }` |
|
||||
| `subagent_delivery_target` | After spawning, to resolve delivery target | Sequential | `{ origin? }` |
|
||||
| `subagent_spawned` | After a subagent is fully spawned | Parallel | `void` |
|
||||
| `subagent_ended` | When a subagent session terminates | Parallel | `void` |
|
||||
|
||||
#### Gateway hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `gateway_start` | After the gateway process is fully started | Parallel | `void` |
|
||||
| `gateway_stop` | When the gateway is shutting down | Parallel | `void` |
|
||||
|
||||
#### Install hooks
|
||||
|
||||
| Hook | When | Execution | Returns |
|
||||
|---|---|---|---|
|
||||
| `before_install` | After built-in security scan, before install proceeds | Sequential | `{ findings?, block?, blockReason? }` |
|
||||
|
||||
<Note>
|
||||
Two hooks (`tool_result_persist` and `before_message_write`) are **synchronous only** — they must not return a Promise. Returning a Promise from these hooks is caught at runtime and the result is discarded with a warning.
|
||||
</Note>
|
||||
|
||||
For full handler signatures and context types, see [Plugin Architecture](/plugins/architecture).
|
||||
|
||||
### Future Events
|
||||
|
||||
The following event types are planned for the internal hook event stream.
|
||||
|
|
|
|||
Loading…
Reference in New Issue