fix: suppress expected PostToolUse errors for subagent and server tools

The SDK fires PostToolUse hooks for Task (subagent) tools before
registerHookCallback() sees the tool_use block, and for server_tool_use
tools (WebSearch) which never register a callback. Since this is
expected behavior, skip the logger.error() call for these tools as the
error output can be confusing for clients. Genuinely unexpected missing
callbacks still log an error with the tool name for debugging.

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,173 @@ describe("Bash terminal output", () => {
       expect(hookMeta.terminal_exit).toBeUndefined();
     });
   });
+
+  describe("PostToolUse hook for unregistered tool_use IDs", () => {
+    // The SDK fires PostToolUse for subagent tools (Task) before
+    // registerHookCallback() sees the tool_use block, and for
+    // server_tool_use (WebSearch) which never registers a callback.
+    // Since this is expected behavior we choose not to log it, as
+    // the error output can be confusing for clients.
+
+    it("should not call logger.error for Task (subagent) tool", async () => {
+      const errors: string[] = [];
+      const spyLogger: Logger = {
+        log: () => {},
+        error: (...args: any[]) => {
+          errors.push(args.map(String).join(" "));
+        },
+      };
+
+      const hook = createPostToolUseHook(spyLogger);
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Task",
+          tool_input: { prompt: "count exported functions" },
+          tool_response: "42 exported functions",
+          tool_use_id: "toolu_subagent_never_registered",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_subagent_never_registered",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(errors).toHaveLength(0);
+    });
+
+    it("should not call logger.error for WebSearch (server_tool_use) tool", async () => {
+      const errors: string[] = [];
+      const spyLogger: Logger = {
+        log: () => {},
+        error: (...args: any[]) => {
+          errors.push(args.map(String).join(" "));
+        },
+      };
+
+      const hook = createPostToolUseHook(spyLogger);
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "WebSearch",
+          tool_input: { query: "test" },
+          tool_response: "results",
+          tool_use_id: "toolu_server_tool_never_registered",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_server_tool_never_registered",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(errors).toHaveLength(0);
+    });
+
+    it("should still call logger.error for genuinely unexpected unregistered tools", async () => {
+      const errors: string[] = [];
+      const spyLogger: Logger = {
+        log: () => {},
+        error: (...args: any[]) => {
+          errors.push(args.map(String).join(" "));
+        },
+      };
+
+      const hook = createPostToolUseHook(spyLogger);
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Read",
+          tool_input: { file_path: "/tmp/test.txt" },
+          tool_response: "file contents",
+          tool_use_id: "toolu_unexpected_missing",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_unexpected_missing",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toContain("toolu_unexpected_missing");
+      expect(errors[0]).toContain("Read");
+    });
+
+    it("should return { continue: true } for any unregistered tool_use ID", async () => {
+      const hook = createPostToolUseHook(mockLogger);
+      const result = await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "WebSearch",
+          tool_input: { query: "test" },
+          tool_response: "results",
+          tool_use_id: "toolu_server_tool_never_registered_2",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_server_tool_never_registered_2",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(result).toEqual({ continue: true });
+    });
+
+    it("should clean up the toolUseCallbacks entry even when unregistered", async () => {
+      // Pre-register a callback for a different ID to verify the
+      // unregistered path doesn't interfere with registered ones.
+      const hookUpdates: any[] = [];
+      const mockClientWithUpdate = {
+        sessionUpdate: async (notification: any) => {
+          hookUpdates.push(notification);
+        },
+      } as unknown as AgentSideConnection;
+
+      registerHookCallback("toolu_registered_2", {
+        onPostToolUseHook: async (_id, _input, _response) => {
+          await mockClientWithUpdate.sessionUpdate({ update: { registered: true } });
+        },
+      });
+
+      const hook = createPostToolUseHook(mockLogger);
+
+      // Fire for unregistered Task — should silently ignore
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Task",
+          tool_input: {},
+          tool_response: "",
+          tool_use_id: "toolu_unregistered_2",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_unregistered_2",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(hookUpdates).toHaveLength(0);
+
+      // Fire for registered ID — should work normally
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Read",
+          tool_input: {},
+          tool_response: "",
+          tool_use_id: "toolu_registered_2",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_registered_2",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(hookUpdates).toHaveLength(1);
+    });
+  });
 });

src/tools.ts

@@ -766,7 +766,18 @@ export const createPostToolUseHook =
           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}`);
+          // The SDK fires PostToolUse for subagent tools (Task) before
+          // registerHookCallback() sees the tool_use block, and for
+          // server_tool_use (WebSearch etc.) which never registers a
+          // callback.  Since this is expected behavior, we skip logging
+          // for these tools as the error output can be confusing for
+          // clients.  Only log for genuinely unexpected cases.
+          const expectedMissing = input.tool_name === "Task" || input.tool_name === "WebSearch";
+          if (!expectedMissing) {
+            logger.error(
+              `No onPostToolUseHook found for tool use ID: ${toolUseID} (tool: ${input.tool_name})`,
+            );
+          }
           delete toolUseCallbacks[toolUseID];
         }
       }