fix: defer PostToolUse hook execution when callback not yet registered

The Claude Agent SDK fires PostToolUse hooks and delivers streaming
content blocks concurrently.  When a tool completes quickly, the hook
fires before our streaming handler has processed the tool_use block
and called registerHookCallback(), causing "No onPostToolUseHook
found" errors and silently dropping the session/update notification.

Instead of logging an error and giving up, createPostToolUseHook now
creates a deferred promise and waits (up to 5s) for
registerHookCallback() to provide the callback.
registerHookCallback() checks for pending deferreds and resolves
them immediately, so the hook proceeds as soon as the streaming
handler catches up.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timvisher-dd

src/tests/tools.test.ts

@@ -11,7 +11,7 @@ import {
   BetaBashCodeExecutionToolResultBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
 import { toAcpNotifications, ToolUseCache, Logger } from "../acp-agent.js";
-import { toolUpdateFromToolResult, createPostToolUseHook } from "../tools.js";
+import { toolUpdateFromToolResult, createPostToolUseHook, registerHookCallback } from "../tools.js";
 
 describe("rawOutput in tool call updates", () => {
   const mockClient = {} as AgentSideConnection;
@@ -1234,4 +1234,170 @@ describe("Bash terminal output", () => {
       expect(hookMeta.terminal_exit).toBeUndefined();
     });
   });
+
+  describe("PostToolUse callback execution contract", () => {
+    // These tests verify the observable contract between PostToolUse
+    // hooks and registerHookCallback, regardless of implementation:
+    //
+    //   1. Callback registered THEN hook fires → callback executes
+    //   2. Hook fires THEN callback registered → callback still executes
+    //   3. No errors logged in either ordering
+    //   4. Callback receives correct toolInput and toolResponse
+    //   5. Multiple hooks with mixed ordering don't interfere
+    //
+    // A helper that builds the hook input object for a given tool call.
+    function postToolUseInput(toolUseId: string, toolName: string, toolInput: unknown = {}, toolResponse: unknown = "") {
+      return {
+        hook_event_name: "PostToolUse",
+        tool_name: toolName,
+        tool_input: toolInput,
+        tool_response: toolResponse,
+        tool_use_id: toolUseId,
+        session_id: "test-session",
+        transcript_path: "/tmp/test",
+        cwd: "/tmp",
+      };
+    }
+
+    it("executes callback when registered before hook fires", async () => {
+      const received: { id: string; input: unknown; response: unknown }[] = [];
+
+      registerHookCallback("toolu_before_1", {
+        onPostToolUseHook: async (id, input, response) => {
+          received.push({ id, input, response });
+        },
+      });
+
+      const hook = createPostToolUseHook(mockLogger);
+      const result = await hook(
+        postToolUseInput("toolu_before_1", "Bash", { command: "ls" }, "file.txt"),
+        "toolu_before_1",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(result).toEqual({ continue: true });
+      expect(received).toHaveLength(1);
+      expect(received[0]).toEqual({
+        id: "toolu_before_1",
+        input: { command: "ls" },
+        response: "file.txt",
+      });
+    });
+
+    it("executes callback when registered after hook fires", async () => {
+      const received: { id: string; input: unknown; response: unknown }[] = [];
+      const hook = createPostToolUseHook(mockLogger);
+
+      // Hook fires first — no callback registered yet.
+      const hookPromise = hook(
+        postToolUseInput("toolu_after_1", "Read", { file_path: "/tmp/f" }, "contents"),
+        "toolu_after_1",
+        { signal: AbortSignal.abort() },
+      );
+
+      // Registration arrives on the next tick (simulates streaming lag).
+      await new Promise((r) => setTimeout(r, 5));
+      registerHookCallback("toolu_after_1", {
+        onPostToolUseHook: async (id, input, response) => {
+          received.push({ id, input, response });
+        },
+      });
+
+      const result = await hookPromise;
+
+      expect(result).toEqual({ continue: true });
+      expect(received).toHaveLength(1);
+      expect(received[0]).toEqual({
+        id: "toolu_after_1",
+        input: { file_path: "/tmp/f" },
+        response: "contents",
+      });
+    });
+
+    it("does not log errors regardless of registration ordering", async () => {
+      const errors: string[] = [];
+      const spyLogger: Logger = {
+        log: () => {},
+        error: (...args: any[]) => {
+          errors.push(args.map(String).join(" "));
+        },
+      };
+
+      const hook = createPostToolUseHook(spyLogger);
+
+      // Case A: register-then-fire
+      registerHookCallback("toolu_order_a", {
+        onPostToolUseHook: async () => {},
+      });
+      await hook(
+        postToolUseInput("toolu_order_a", "Bash"),
+        "toolu_order_a",
+        { signal: AbortSignal.abort() },
+      );
+
+      // Case B: fire-then-register
+      const hookPromise = hook(
+        postToolUseInput("toolu_order_b", "Grep"),
+        "toolu_order_b",
+        { signal: AbortSignal.abort() },
+      );
+      await new Promise((r) => setTimeout(r, 5));
+      registerHookCallback("toolu_order_b", {
+        onPostToolUseHook: async () => {},
+      });
+      await hookPromise;
+
+      expect(errors).toHaveLength(0);
+    });
+
+    it("keeps hooks independent when some are pre-registered and some are late", async () => {
+      const callOrder: string[] = [];
+      const hook = createPostToolUseHook(mockLogger);
+
+      // Register callback A upfront.
+      registerHookCallback("toolu_mix_a", {
+        onPostToolUseHook: async (id) => { callOrder.push(id); },
+      });
+
+      // Fire hook B first (no registration yet), then hook A.
+      const hookBPromise = hook(
+        postToolUseInput("toolu_mix_b", "Read"),
+        "toolu_mix_b",
+        { signal: AbortSignal.abort() },
+      );
+
+      await hook(
+        postToolUseInput("toolu_mix_a", "Bash"),
+        "toolu_mix_a",
+        { signal: AbortSignal.abort() },
+      );
+
+      // A should have executed already.
+      expect(callOrder).toEqual(["toolu_mix_a"]);
+
+      // Now register B — its hook should complete.
+      registerHookCallback("toolu_mix_b", {
+        onPostToolUseHook: async (id) => { callOrder.push(id); },
+      });
+
+      await hookBPromise;
+      expect(callOrder).toEqual(["toolu_mix_a", "toolu_mix_b"]);
+    });
+
+    it("always returns { continue: true } even in the race case", async () => {
+      const hook = createPostToolUseHook(mockLogger);
+
+      const hookPromise = hook(
+        postToolUseInput("toolu_continue_1", "Agent"),
+        "toolu_continue_1",
+        { signal: AbortSignal.abort() },
+      );
+
+      registerHookCallback("toolu_continue_1", {
+        onPostToolUseHook: async () => {},
+      });
+
+      expect(await hookPromise).toEqual({ continue: true });
+    });
+  });
 });

src/tools.ts

@@ -727,6 +727,25 @@ const toolUseCallbacks: {
   };
 } = {};
 
+/*
+ * When the SDK fires PostToolUse before the streaming handler has called
+ * registerHookCallback(), we store a deferred here.  registerHookCallback()
+ * checks this map and resolves the deferred so the waiting hook can proceed.
+ */
+const pendingHooks: {
+  [toolUseId: string]: {
+    resolve: (
+      cb: (toolUseID: string, toolInput: unknown, toolResponse: unknown) => Promise<void>,
+    ) => void;
+    promise: Promise<
+      (toolUseID: string, toolInput: unknown, toolResponse: unknown) => Promise<void>
+    >;
+  };
+} = {};
+
+/** Maximum time (ms) to wait for a callback registration before giving up. */
+const HOOK_WAIT_TIMEOUT_MS = 5_000;
+
 /* Setup callbacks that will be called when receiving hooks from Claude Code */
 export const registerHookCallback = (
   toolUseID: string,
@@ -743,6 +762,12 @@ export const registerHookCallback = (
   toolUseCallbacks[toolUseID] = {
     onPostToolUseHook,
   };
+
+  // If a PostToolUse hook is already waiting for this ID, hand it the callback.
+  if (onPostToolUseHook && pendingHooks[toolUseID]) {
+    pendingHooks[toolUseID].resolve(onPostToolUseHook);
+    delete pendingHooks[toolUseID];
+  }
 };
 
 /* A callback for Claude Code that is called when receiving a PostToolUse hook */
@@ -761,13 +786,37 @@ export const createPostToolUseHook =
       }
 
       if (toolUseID) {
-        const onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
+        let onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
         if (onPostToolUseHook) {
           await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
           delete toolUseCallbacks[toolUseID]; // Cleanup after execution
         } else {
-          logger.error(`No onPostToolUseHook found for tool use ID: ${toolUseID}`);
-          delete toolUseCallbacks[toolUseID];
+          // The SDK fired PostToolUse before the streaming handler called
+          // registerHookCallback().  Wait for registration (with timeout).
+          let resolve: (typeof pendingHooks)[string]["resolve"];
+          const promise = new Promise<
+            (toolUseID: string, toolInput: unknown, toolResponse: unknown) => Promise<void>
+          >((r) => {
+            resolve = r;
+          });
+          pendingHooks[toolUseID] = { resolve: resolve!, promise };
+
+          const cb = await Promise.race([
+            promise,
+            new Promise<null>((r) => setTimeout(() => r(null), HOOK_WAIT_TIMEOUT_MS)),
+          ]);
+
+          delete pendingHooks[toolUseID];
+
+          if (cb) {
+            await cb(toolUseID, input.tool_input, input.tool_response);
+            delete toolUseCallbacks[toolUseID];
+          } else {
+            logger.error(
+              `PostToolUse hook timed out waiting for callback registration: ${toolUseID}`,
+            );
+            delete toolUseCallbacks[toolUseID];
+          }
         }
       }
     }