diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 9532f7cb5..9fc47af9b 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "c0ec58f4b6906ad06fd4c6f265d43be053b2d193",
-  "syncedAt": "2026-04-28T17:07:02.718Z"
+  "sha": "7d2d8732d0a19319f8b2bcd572a7bf1146566ed3",
+  "syncedAt": "2026-04-28T17:14:03.986Z"
 }
diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md
index 723dcbe13..5cc106798 100644
--- a/docs/plugins/hooks.md
+++ b/docs/plugins/hooks.md
@@ -52,6 +52,15 @@ export default definePluginEntry({
 Hook handlers run sequentially in descending `priority`. Same-priority hooks
 keep registration order.
 
+`api.on(name, handler, opts?)` accepts:
+
+- `priority` — handler ordering (higher runs first).
+- `timeoutMs` — optional per-hook budget. When set, the hook runner aborts that
+  handler after the budget elapses and continues with the next one, instead of
+  letting slow setup or recall work consume the caller's configured model
+  timeout. Omit it to use the default observation/decision timeout that the
+  hook runner applies generically.
+
 Each hook receives `event.context.pluginConfig`, the resolved config for the
 plugin that registered that handler. Use it for hook decisions that need
 current plugin options; OpenClaw injects it per handler without mutating the