From 423dce7ccd55cf97d89f99bc6770ad8c99ec5607 Mon Sep 17 00:00:00 2001 From: zeroaltitude Date: Fri, 6 Mar 2026 18:47:20 -0700 Subject: [PATCH] docs(session-memory): clarify hook ordering limitation for blockSessionSave Bundled hooks register before managed/workspace hooks in FIFO order, so blockSessionSave only works when set by typed plugin hooks (which fire earlier in the lifecycle) or extraDirs hooks. Document this limitation honestly rather than claiming incorrect ordering. --- src/hooks/bundled/session-memory/handler.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/hooks/bundled/session-memory/handler.ts b/src/hooks/bundled/session-memory/handler.ts index ee6eacbf17f..39bc547f5e1 100644 --- a/src/hooks/bundled/session-memory/handler.ts +++ b/src/hooks/bundled/session-memory/handler.ts @@ -209,10 +209,13 @@ const saveSessionToMemory: HookHandler = async (event) => { const context = event.context || {}; // Check if another hook (e.g., security plugin) blocked the save. - // Internal hooks execute sequentially in FIFO registration order. - // Managed/workspace hooks that set blockSessionSave or sessionSaveContent - // must register for the same event (command:new / command:reset) and will - // run before this bundled handler as long as they are loaded first. + // NOTE: Internal hooks execute sequentially in FIFO registration order. + // Bundled hooks register before managed/workspace hooks (see workspace.ts + // loadHookEntries merge order), so this check only works when the policy + // decision is set by a typed plugin hook (registerTypedHook) that fires + // earlier in the agent lifecycle, or by a hook loaded via extraDirs that + // registers before bundled hooks. Managed/workspace internal hooks that + // set blockSessionSave on the same event will run AFTER this handler. if (context.blockSessionSave === true) { log.debug("Session save blocked by upstream hook"); return;