From 2e246b47b97f08e11620bb8ba32667d52e330397 Mon Sep 17 00:00:00 2001
From: Jacob Tomlinson <jtomlinson@nvidia.com>
Date: Sun, 22 Mar 2026 21:09:22 +0000
Subject: [PATCH] docs: fix hook load order, command event payload, and
 session-memory confirmation

---
 docs/automation/hooks.md                 | 29 +++++++++++++-----------
 src/hooks/bundled/session-memory/HOOK.md |  1 -
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md
index f7e3a60a138..71f4ac824bc 100644
--- a/docs/automation/hooks.md
+++ b/docs/automation/hooks.md
@@ -82,13 +82,12 @@ Hooks run inside the Gateway process. Treat bundled hooks, managed hooks, and `h
 
 ## Hook Discovery
 
-Hooks are automatically discovered from these directories:
+Hooks are automatically discovered from these directories, in order of increasing override precedence:
 
-1. **Bundled hooks**: `<openclaw>/dist/hooks/bundled/` (shipped with OpenClaw)
+1. **Bundled hooks**: shipped with OpenClaw; located at `<openclaw>/dist/hooks/bundled/` for npm installs (or a sibling `hooks/bundled/` for compiled binaries)
 2. **Plugin hooks**: hooks bundled inside installed plugins (see [Plugin hooks](/plugins/architecture#provider-runtime-hooks))
-3. **Managed hooks**: `~/.openclaw/hooks/` (user-installed, shared across workspaces; can override bundled and plugin hooks)
-4. **Extra hook directories**: `hooks.internal.load.extraDirs` (operator-configured shared hook folders; treated as managed)
-5. **Workspace hooks**: `<workspace>/hooks/` (per-agent, disabled by default until explicitly enabled; cannot override hooks from other sources)
+3. **Managed hooks**: `~/.openclaw/hooks/` (user-installed, shared across workspaces; can override bundled and plugin hooks). **Extra hook directories** configured via `hooks.internal.load.extraDirs` are also treated as managed hooks and share the same override precedence.
+4. **Workspace hooks**: `<workspace>/hooks/` (per-agent, disabled by default until explicitly enabled; cannot override hooks from other sources)
 
 Workspace hooks can add new hook names for a repo, but they cannot override bundled, managed, or plugin-provided hooks with the same name.
 
@@ -226,15 +225,17 @@ Each event includes:
   timestamp: Date,             // When the event occurred
   messages: string[],          // Push messages here to send to user
   context: {
-    // Command events:
-    sessionEntry?: SessionEntry,
-    sessionId?: string,
-    sessionFile?: string,
-    commandSource?: string,    // e.g., 'whatsapp', 'telegram'
+    // Command events (command:new, command:reset):
+    sessionEntry?: SessionEntry,       // current session entry
+    previousSessionEntry?: SessionEntry, // pre-reset entry (preferred for session-memory)
+    commandSource?: string,            // e.g., 'whatsapp', 'telegram'
     senderId?: string,
     workspaceDir?: string,
-    bootstrapFiles?: WorkspaceBootstrapFile[],
     cfg?: OpenClawConfig,
+    // Command events (command:stop only):
+    sessionId?: string,
+    // Agent bootstrap events (agent:bootstrap):
+    bootstrapFiles?: WorkspaceBootstrapFile[],
     // Message events (see Message Events section for full details):
     from?: string,             // message:received
     to?: string,               // message:sent
@@ -509,7 +510,7 @@ Hooks can have custom configuration:
 
 ### Extra Directories
 
-Load hooks from additional directories:
+Load hooks from additional directories (treated as managed hooks, same override precedence):
 
 ```json
 {
@@ -915,10 +916,12 @@ test("my handler works", async () => {
 ```
 Gateway startup
     ↓
-Scan directories (bundled → plugin → managed → workspace)
+Scan directories (bundled → plugin → managed + extra dirs → workspace)
     ↓
 Parse HOOK.md files
     ↓
+Sort by override precedence (bundled < plugin < managed < workspace)
+    ↓
 Check eligibility (bins, env, config, os)
     ↓
 Load handlers from eligible hooks
diff --git a/src/hooks/bundled/session-memory/HOOK.md b/src/hooks/bundled/session-memory/HOOK.md
index c963e17b76c..b087e8fe164 100644
--- a/src/hooks/bundled/session-memory/HOOK.md
+++ b/src/hooks/bundled/session-memory/HOOK.md
@@ -26,7 +26,6 @@ When you run `/new` or `/reset` to start a fresh session:
 2. **Extracts conversation** - Reads the last N user/assistant messages from the session (default: 15, configurable)
 3. **Generates descriptive slug** - Uses LLM to create a meaningful filename slug based on conversation content
 4. **Saves to memory** - Creates a new file at `<workspace>/memory/YYYY-MM-DD-slug.md`
-5. **Sends confirmation** - Notifies you with the file path
 
 ## Output Format