fix(plugins): snapshot before_tool_call context payloads

Reapor-Yurnero · Reapor-Yurnero · commit 44ef0440f832 · 2026-03-30T23:46:43.000-04:00
diff --git a/src/agents/pi-tools.before-tool-call.context.test.ts b/src/agents/pi-tools.before-tool-call.context.test.ts
@@ -26,6 +26,11 @@ describe("before_tool_call hook context payload", () => {
         content: [{ type: "text", text: "check this call" }],
         timestamp: Date.now(),
       },
+      {
+        role: "user",
+        content: [{ type: "text", text: "followup" }],
+        timestamp: Date.now(),
+      },
     ];
     const tools = [
       {
@@ -64,4 +69,79 @@ describe("before_tool_call hook context payload", () => {
       }),
     );
   });
+
+  it("clones and freezes params/messages/tools snapshots before dispatch", async () => {
+    const runBeforeToolCall = vi.fn().mockResolvedValue(undefined);
+    mockGetGlobalHookRunner.mockReturnValue({
+      hasHooks: vi.fn((hookName: string) => hookName === "before_tool_call"),
+      runBeforeToolCall,
+      // oxlint-disable-next-line typescript/no-explicit-any
+    } as any);
+
+    const params = { path: "/tmp/file" };
+    const messages: AgentMessage[] = [
+      {
+        role: "user",
+        content: [{ type: "text", text: "check this call" }],
+        timestamp: Date.now(),
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: "followup" }],
+        timestamp: Date.now(),
+      },
+    ];
+    const tools = [
+      {
+        name: "read",
+        description: "Read a file",
+        parameters: { type: "object", properties: { path: { type: "string" } } },
+      },
+    ];
+
+    await runBeforeToolCallHook({
+      toolName: "read",
+      params,
+      ctx: {
+        getMessages: () => messages,
+        getTools: () => tools,
+      },
+    });
+
+    const [event] = runBeforeToolCall.mock.calls[0] as [
+      {
+        params: Record<string, unknown>;
+        messages?: AgentMessage[];
+        tools?: Array<{ parameters?: { properties?: { path?: { type?: string } } } }>;
+      },
+    ];
+
+    expect(event.params).not.toBe(params);
+    expect(event.messages).not.toBe(messages);
+    expect(event.tools).not.toBe(tools);
+    expect(Object.isFrozen(event)).toBe(true);
+    expect(Object.isFrozen(event.params)).toBe(true);
+    expect(Object.isFrozen(event.messages ?? [])).toBe(true);
+    expect(Object.isFrozen(event.messages?.[0] ?? {})).toBe(true);
+    expect(Object.isFrozen(event.tools ?? [])).toBe(true);
+    expect(Object.isFrozen(event.tools?.[0] ?? {})).toBe(true);
+
+    expect(() => {
+      event.params.path = "/tmp/hacked";
+    }).toThrow(TypeError);
+    expect(() => {
+      if (event.messages) {
+        event.messages[0] = event.messages[1];
+      }
+    }).toThrow(TypeError);
+    expect(() => {
+      if (event.tools?.[0]?.parameters?.properties?.path) {
+        event.tools[0].parameters.properties.path.type = "number";
+      }
+    }).toThrow(TypeError);
+
+    expect(params.path).toBe("/tmp/file");
+    expect(messages[0]?.role).toBe("user");
+    expect(tools[0]?.parameters?.properties?.path?.type).toBe("string");
+  });
 });
diff --git a/src/agents/pi-tools.before-tool-call.ts b/src/agents/pi-tools.before-tool-call.ts
@@ -42,6 +42,26 @@ const loadBeforeToolCallRuntime = createLazyRuntimeSurface(
   ({ beforeToolCallRuntime }) => beforeToolCallRuntime,
 );
 
+function freezeHookSnapshot<T>(value: T): T {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      freezeHookSnapshot(item);
+    }
+    return Object.freeze(value);
+  }
+  if (isPlainObject(value)) {
+    for (const nested of Object.values(value)) {
+      freezeHookSnapshot(nested);
+    }
+    return Object.freeze(value);
+  }
+  return value;
+}
+
+function cloneHookSnapshot<T>(value: T): T {
+  return freezeHookSnapshot(structuredClone(value));
+}
+
 function buildAdjustedParamsKey(params: { runId?: string; toolCallId: string }): string {
   if (params.runId && params.runId.trim()) {
     return `${params.runId}:${params.toolCallId}`;
@@ -199,18 +219,16 @@ export async function runBeforeToolCallHook(args: {
       ...(args.ctx?.runId && { runId: args.ctx.runId }),
       ...(args.toolCallId && { toolCallId: args.toolCallId }),
     };
-    const hookResult = await hookRunner.runBeforeToolCall(
-      {
-        toolName,
-        params: normalizedParams,
-        ...(args.ctx?.runId && { runId: args.ctx.runId }),
-        ...(args.toolCallId && { toolCallId: args.toolCallId }),
-        ...(args.ctx?.getSystemPrompt && { systemPrompt: args.ctx.getSystemPrompt() }),
-        ...(args.ctx?.getMessages && { messages: args.ctx.getMessages() }),
-        ...(args.ctx?.getTools && { tools: args.ctx.getTools() }),
-      },
-      toolContext,
-    );
+    const hookEvent = freezeHookSnapshot({
+      toolName,
+      params: cloneHookSnapshot(normalizedParams),
+      ...(args.ctx?.runId && { runId: args.ctx.runId }),
+      ...(args.toolCallId && { toolCallId: args.toolCallId }),
+      ...(args.ctx?.getSystemPrompt && { systemPrompt: args.ctx.getSystemPrompt() }),
+      ...(args.ctx?.getMessages && { messages: cloneHookSnapshot(args.ctx.getMessages()) }),
+      ...(args.ctx?.getTools && { tools: cloneHookSnapshot(args.ctx.getTools()) }),
+    });
+    const hookResult = await hookRunner.runBeforeToolCall(hookEvent, toolContext);
 
     if (hookResult?.block) {
       return {
