#12819: docs(hooks): document plugin hook names and clarify naming
docs
stale
Cluster:
Plugin Hook Enhancements
## Summary
Documents currently implemented plugin hook names and clarifies internal-hook vs plugin-hook naming to prevent confusion.
## What changed
- Updated `docs/tools/plugin.md` (`Plugin hooks` section):
- Added the currently available plugin hook names:
- `before_agent_start`, `agent_end`
- `message_received`, `message_sending`, `message_sent`
- `before_tool_call`, `after_tool_call`
- `session_start`, `session_end`
- Added a naming note to use underscore hook names exactly (for example `message_received`, not `message:received`).
- Updated `docs/automation/hooks.md`:
- Renamed `Future Events` to `Future Events (internal hooks)`
- Clarified that the listed `type:action` names belong to internal hooks
- Added a note pointing readers to plugin hook names under `/tools/plugin#plugin-hooks`
## Why
Issue #12436 reports confusion where plugin hooks appeared undocumented and `message:received` looked like a future-only event. The actual confusion is between two hook systems with different naming conventions (internal `type:action` vs plugin underscore names). This PR documents the available plugin hooks and disambiguates naming.
Closes #12436
## Contributing checklist
- [x] AI-assisted: yes (prepared with OpenClaw assistant, model: `openai-codex/gpt-5.3-codex`)
- [x] Testing level: lightly tested (docs-only change; link/build/test not run for this docs PR)
- [x] Confirmed understanding of change and impact
Most Similar PRs
#10680: docs: clarify api.on() vs api.registerHook() for plugin hooks
by yassinebkr · 2026-02-06
78.9%
#20580: feat(hooks): bridge after_tool_call to internal hook handler system
by CryptoKrad · 2026-02-19
67.7%
#18860: feat(agents): expose tools and their schemas via new after_tools_re...
by lan17 · 2026-02-17
66.0%
#18810: feat(hooks): wire before_tool_call/after_tool_call with veto support
by vjranagit · 2026-02-17
65.3%
#19422: fix: pass session context to plugin tool hooks in toToolDefinitions
by namabile · 2026-02-17
65.0%
#4881: docs(plugin): clarify memory-lancedb is bundled (no npm install nee...
by AverageSuami · 2026-01-30
64.9%
#22691: docs(plugins): add askpi and askcodex to community plugins
by dougvk · 2026-02-21
64.5%
#19565: feat: add agent lifecycle hook events (session, message, error)
by tag-assistant · 2026-02-17
64.3%
#16028: feat/before-tool-result
by ambushalgorithm · 2026-02-14
64.3%
#20067: feat(plugins): add before_agent_reply hook for message interception
by JoshuaLelon · 2026-02-18
64.1%