Summary

Adds the missing wiring for the before_tool_call plugin hook, enabling plugins to intercept, validate, modify, or block tool calls before execution.

The hook infrastructure (types, runner, handler merging) already existed in src/plugins/hooks.ts but was never actually invoked in the tool execution path. This PR adds the missing piece.

Changes

• New file: src/agents/pi-tools.before-call-hook.ts

  • wrapToolWithBeforeCallHook() - wraps a single tool
  • wrapToolsWithBeforeCallHook() - wraps all tools in array

• Modified: src/agents/pi-embedded-runner/run/attempt.ts

  • Wraps tools after sanitization if before_tool_call hooks are registered
  • Only wraps if hooks exist (zero overhead when no plugins use this hook)

Hook Behavior

Plugins can register a before_tool_call handler via api.on("before_tool_call", ...) to:

1. Allow (default) - tool executes normally
2. Modify params - return { params: modifiedParams } to change tool arguments
3. Block - return { block: true, blockReason: "..." } to prevent execution

Example Plugin Usage

api.on("before_tool_call", (event, ctx) => {
  const { toolName, params } = event;
  
  // Block dangerous commands
  if (toolName === "exec" && params.command?.includes("rm -rf /")) {
    return { block: true, blockReason: "Refusing to delete root filesystem" };
  }
  
  // Allow everything else
  return {};
});

Test Plan

• Verify existing tool_result_persist hook still works
• Test plugin with before_tool_call handler can log tool calls
• Test plugin can block tool calls with custom reason
• Test plugin can modify tool parameters
• Verify no performance impact when no hooks registered

Closes #1733

Generated with Claude Code