Summary

Remove the duplicate runBeforeToolCallHook call from toToolDefinitions so the before_tool_call hook fires exactly once per tool invocation instead of 2–3 times.

Root Cause

Tools go through two layers that both independently call runBeforeToolCallHook:

1. wrapToolWithBeforeToolCallHook (pi-tools.ts:460) — wraps tool.execute with hook call, includes agentId/sessionKey context
2. toToolDefinitions (pi-tool-definition-adapter.ts:95) — wraps again with another hook call, but without context

Since tool-split.ts:15 calls toToolDefinitions(tools) on tools that are already wrapped by step 1, the hook fires twice per invocation.

Fix

Remove the runBeforeToolCallHook call from toToolDefinitions (layer 2). The hook is already invoked by wrapToolWithBeforeToolCallHook (layer 1) which has the full agentId/sessionKey context.

toClientToolDefinitions is not changed — client tools don't go through wrapToolWithBeforeToolCallHook, so they correctly call the hook directly.

  execute: async (...args) => {
    const { toolCallId, params, onUpdate, signal } = splitToolExecuteArgs(args);
    try {
-     const hookOutcome = await runBeforeToolCallHook({ toolName, params, toolCallId });
-     if (hookOutcome.blocked) { throw new Error(hookOutcome.reason); }
-     const adjustedParams = hookOutcome.params;
-     const result = await tool.execute(toolCallId, adjustedParams, signal, onUpdate);
+     // before_tool_call hook is already invoked by wrapToolWithBeforeToolCallHook
+     // (applied in pi-tools.ts) before tools reach toToolDefinitions (#15502).
+     const result = await tool.execute(toolCallId, params, signal, onUpdate);

Before (on main — real environment, zero mocks)

Registered a real before_tool_call hook via initializeGlobalHookRunner with a real PluginRegistry, then executed a tool through the full wrapToolWithBeforeToolCallHook → toToolDefinitions → runBeforeToolCallHook → createHookRunner.runBeforeToolCall pipeline:

Hook fired 2 times:
  - toolName=web_fetch, params={"url":"https://example.com"}
  - toolName=web_fetch, params={"url":"https://example.com"}
❌ BUG CONFIRMED: real before_tool_call hook handler fired 2 times (expected 1)

After (on fix branch)

✓ fires hook exactly once when tool goes through wrap + toToolDefinitions
✓ dispatches after_tool_call once on successful adapter execution
✓ passes modified params to client tool callbacks

Test Files  3 passed (3)
     Tests  12 passed (12)

Changes

• src/agents/pi-tool-definition-adapter.ts: remove duplicate runBeforeToolCallHook call from toToolDefinitions
• src/agents/pi-tools.before-tool-call.e2e.test.ts: add regression test verifying hook fires exactly once through the full wrap + toToolDefinitions pipeline
• src/agents/pi-tool-definition-adapter.after-tool-call.e2e.test.ts: update after_tool_call test to reflect that params are no longer adjusted inside toToolDefinitions
• CHANGELOG.md: add entry

Closes #15502