refactor: align agent tool params with upstream pi

Author: steipete

docs/pi.md

@@ -503,7 +503,7 @@ if (sandboxRoot) {
 
 - Refusal magic string scrubbing
 - Turn validation for consecutive roles
-- Claude Code parameter compatibility
+- Strict upstream Pi tool parameter validation
 
 ### Google/Gemini
 

src/agents/pi-tool-definition-adapter.logging.test.ts

@@ -13,8 +13,8 @@ vi.mock("../logger.js", () => ({
 }));
 
 let toToolDefinitions: typeof import("./pi-tool-definition-adapter.js").toToolDefinitions;
-let wrapToolParamNormalization: typeof import("./pi-tools.params.js").wrapToolParamNormalization;
-let CLAUDE_PARAM_GROUPS: typeof import("./pi-tools.params.js").CLAUDE_PARAM_GROUPS;
+let wrapToolParamValidation: typeof import("./pi-tools.params.js").wrapToolParamValidation;
+let REQUIRED_PARAM_GROUPS: typeof import("./pi-tools.params.js").REQUIRED_PARAM_GROUPS;
 let logError: typeof import("../logger.js").logError;
 
 type ToolExecute = ReturnType<
@@ -25,7 +25,7 @@ const extensionContext = {} as Parameters<ToolExecute>[4];
 describe("pi tool definition adapter logging", () => {
   beforeAll(async () => {
     ({ toToolDefinitions } = await import("./pi-tool-definition-adapter.js"));
-    ({ wrapToolParamNormalization, CLAUDE_PARAM_GROUPS } = await import("./pi-tools.params.js"));
+    ({ wrapToolParamValidation, REQUIRED_PARAM_GROUPS } = await import("./pi-tools.params.js"));
     ({ logError } = await import("../logger.js"));
   });
 
@@ -41,16 +41,20 @@ describe("pi tool definition adapter logging", () => {
       description: "edits files",
       parameters: Type.Object({
         path: Type.String(),
-        oldText: Type.String(),
-        newText: Type.String(),
+        edits: Type.Array(
+          Type.Object({
+            oldText: Type.String(),
+            newText: Type.String(),
+          }),
+        ),
       }),
       execute: async () => ({
         content: [{ type: "text" as const, text: "ok" }],
         details: { ok: true },
       }),
     } satisfies AgentTool;
 
-    const tool = wrapToolParamNormalization(baseTool, CLAUDE_PARAM_GROUPS.edit);
+    const tool = wrapToolParamValidation(baseTool, REQUIRED_PARAM_GROUPS.edit);
     const [def] = toToolDefinitions([tool]);
     if (!def) {
       throw new Error("missing tool definition");
@@ -60,7 +64,7 @@ describe("pi tool definition adapter logging", () => {
 
     expect(logError).toHaveBeenCalledWith(
       expect.stringContaining(
-        '[tools] edit failed: Missing required parameters: oldText alias, newText alias (received: path). Supply correct parameters before retrying. raw_params={"path":"notes.txt"}',
+        '[tools] edit failed: Missing required parameter: edits (received: path). Supply correct parameters before retrying. raw_params={"path":"notes.txt"}',
       ),
     );
   });
@@ -86,7 +90,7 @@ describe("pi tool definition adapter logging", () => {
       execute,
     } satisfies AgentTool;
 
-    const tool = wrapToolParamNormalization(baseTool, CLAUDE_PARAM_GROUPS.edit);
+    const tool = wrapToolParamValidation(baseTool, REQUIRED_PARAM_GROUPS.edit);
     const [def] = toToolDefinitions([tool]);
     if (!def) {
       throw new Error("missing tool definition");

src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping-e.test.ts

@@ -1,41 +1,12 @@
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import { Type } from "@sinclair/typebox";
 import { describe, expect, it, vi } from "vitest";
-import {
-  patchToolSchemaForClaudeCompatibility,
-  wrapToolParamNormalization,
-} from "./pi-tools.params.js";
+import { REQUIRED_PARAM_GROUPS, wrapToolParamValidation } from "./pi-tools.params.js";
 import { cleanToolSchemaForGemini } from "./pi-tools.schema.js";
 
 describe("createOpenClawCodingTools", () => {
-  describe("Claude/Gemini alias support", () => {
-    it("adds Claude-style aliases to schemas without dropping metadata", () => {
-      const base: AgentTool = {
-        name: "write",
-        label: "write",
-        description: "test",
-        parameters: Type.Object({
-          path: Type.String({ description: "Path" }),
-          content: Type.String({ description: "Body" }),
-        }),
-        execute: vi.fn(),
-      };
-
-      const patched = patchToolSchemaForClaudeCompatibility(base);
-      const params = patched.parameters as {
-        additionalProperties?: unknown;
-        properties?: Record<string, unknown>;
-        required?: string[];
-      };
-      const props = params.properties ?? {};
-
-      expect(props.file_path).toEqual(props.path);
-      expect(params.additionalProperties).toBe(false);
-      expect(params.required ?? []).not.toContain("path");
-      expect(params.required ?? []).not.toContain("file_path");
-    });
-
-    it("normalizes file_path to path and enforces required groups at runtime", async () => {
+  describe("Gemini cleanup and strict param validation", () => {
+    it("enforces canonical path/content at runtime", async () => {
       const execute = vi.fn(async (_id, args) => args);
       const tool: AgentTool = {
         name: "write",
@@ -48,12 +19,9 @@ describe("createOpenClawCodingTools", () => {
         execute,
       };
 
-      const wrapped = wrapToolParamNormalization(tool, [
-        { keys: ["path", "file_path"], label: "path (path or file_path)" },
-        { keys: ["content"], label: "content" },
-      ]);
+      const wrapped = wrapToolParamValidation(tool, REQUIRED_PARAM_GROUPS.write);
 
-      await wrapped.execute("tool-1", { file_path: "foo.txt", content: "x" });
+      await wrapped.execute("tool-1", { path: "foo.txt", content: "x" });
       expect(execute).toHaveBeenCalledWith(
         "tool-1",
         { path: "foo.txt", content: "x" },
@@ -67,14 +35,14 @@ describe("createOpenClawCodingTools", () => {
       await expect(wrapped.execute("tool-2", { content: "x" })).rejects.toThrow(
         /Supply correct parameters before retrying\./,
       );
-      await expect(wrapped.execute("tool-3", { file_path: "   ", content: "x" })).rejects.toThrow(
+      await expect(wrapped.execute("tool-3", { path: "   ", content: "x" })).rejects.toThrow(
         /Missing required parameter/,
       );
-      await expect(wrapped.execute("tool-3", { file_path: "   ", content: "x" })).rejects.toThrow(
+      await expect(wrapped.execute("tool-3", { path: "   ", content: "x" })).rejects.toThrow(
         /Supply correct parameters before retrying\./,
       );
       await expect(wrapped.execute("tool-4", {})).rejects.toThrow(
-        /Missing required parameters: path \(path or file_path\), content/,
+        /Missing required parameters: path, content/,
       );
       await expect(wrapped.execute("tool-4", {})).rejects.toThrow(
         /Supply correct parameters before retrying\./,

src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping-f.test.ts

@@ -8,26 +8,25 @@ import { createOpenClawCodingTools } from "./pi-tools.js";
 import { expectReadWriteEditTools } from "./test-helpers/pi-tools-fs-helpers.js";
 
 describe("createOpenClawCodingTools", () => {
-  it("accepts Claude Code parameter aliases for read/write/edit", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-alias-"));
+  it("accepts canonical parameters for read/write/edit", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-canonical-"));
     try {
       const tools = createOpenClawCodingTools({ workspaceDir: tmpDir });
       const { readTool, writeTool, editTool } = expectReadWriteEditTools(tools);
 
-      const filePath = "alias-test.txt";
-      await writeTool?.execute("tool-alias-1", {
-        file_path: filePath,
+      const filePath = "canonical-test.txt";
+      await writeTool?.execute("tool-canonical-1", {
+        path: filePath,
         content: "hello world",
       });
 
-      await editTool?.execute("tool-alias-2", {
-        file_path: filePath,
-        old_string: "world",
-        new_string: "universe",
+      await editTool?.execute("tool-canonical-2", {
+        path: filePath,
+        edits: [{ oldText: "world", newText: "universe" }],
       });
 
-      const result = await readTool?.execute("tool-alias-3", {
-        file_path: filePath,
+      const result = await readTool?.execute("tool-canonical-3", {
+        path: filePath,
       });
 
       const textBlocks = result?.content?.filter((block) => block.type === "text") as
@@ -40,62 +39,59 @@ describe("createOpenClawCodingTools", () => {
     }
   });
 
-  it("accepts broader file/edit alias variants", async () => {
-    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-alias-broad-"));
+  it("rejects legacy alias parameters", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-legacy-alias-"));
     try {
       const tools = createOpenClawCodingTools({ workspaceDir: tmpDir });
       const { readTool, writeTool, editTool } = expectReadWriteEditTools(tools);
 
-      await writeTool?.execute("tool-alias-broad-1", {
-        file: "broad-alias.txt",
-        content: "hello old value",
-      });
-
-      await editTool?.execute("tool-alias-broad-2", {
-        filePath: "broad-alias.txt",
-        old_text: "old",
-        newString: "new",
-      });
-
-      const result = await readTool?.execute("tool-alias-broad-3", {
-        file: "broad-alias.txt",
-      });
-
-      const textBlocks = result?.content?.filter((block) => block.type === "text") as
-        | Array<{ text?: string }>
-        | undefined;
-      const combinedText = textBlocks?.map((block) => block.text ?? "").join("\n");
-      expect(combinedText).toContain("hello new value");
+      await expect(
+        writeTool?.execute("tool-legacy-write", {
+          file: "legacy.txt",
+          content: "hello old value",
+        }),
+      ).rejects.toThrow(/Missing required parameter: path/);
+
+      await expect(
+        editTool?.execute("tool-legacy-edit", {
+          filePath: "legacy.txt",
+          old_text: "old",
+          newString: "new",
+        }),
+      ).rejects.toThrow(/Missing required parameters: path, edits/);
+
+      await expect(
+        readTool?.execute("tool-legacy-read", {
+          file_path: "legacy.txt",
+        }),
+      ).rejects.toThrow(/Missing required parameter: path/);
     } finally {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
-  it("coerces structured content blocks for write", async () => {
+  it("rejects structured content blocks for write", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-structured-write-"));
     try {
       const tools = createOpenClawCodingTools({ workspaceDir: tmpDir });
       const writeTool = tools.find((tool) => tool.name === "write");
       expect(writeTool).toBeDefined();
 
-      await writeTool?.execute("tool-structured-write", {
-        path: "structured-write.js",
-        content: [
-          { type: "text", text: "const path = require('path');\n" },
-          { type: "input_text", text: "const root = path.join(process.env.HOME, 'clawd');\n" },
-        ],
-      });
-
-      const written = await fs.readFile(path.join(tmpDir, "structured-write.js"), "utf8");
-      expect(written).toBe(
-        "const path = require('path');\nconst root = path.join(process.env.HOME, 'clawd');\n",
-      );
+      await expect(
+        writeTool?.execute("tool-structured-write", {
+          path: "structured-write.js",
+          content: [
+            { type: "text", text: "const path = require('path');\n" },
+            { type: "input_text", text: "const root = path.join(process.env.HOME, 'clawd');\n" },
+          ],
+        }),
+      ).rejects.toThrow(/Missing required parameter: content/);
     } finally {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }
   });
 
-  it("coerces structured old/new text blocks for edit", async () => {
+  it("rejects structured edit payloads", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-structured-edit-"));
     try {
       const filePath = path.join(tmpDir, "structured-edit.js");
@@ -105,14 +101,17 @@ describe("createOpenClawCodingTools", () => {
       const editTool = tools.find((tool) => tool.name === "edit");
       expect(editTool).toBeDefined();
 
-      await editTool?.execute("tool-structured-edit", {
-        file_path: "structured-edit.js",
-        old_string: [{ type: "text", text: "old" }],
-        new_string: [{ kind: "text", value: "new" }],
-      });
-
-      const edited = await fs.readFile(filePath, "utf8");
-      expect(edited).toBe("const value = 'new';\n");
+      await expect(
+        editTool?.execute("tool-structured-edit", {
+          path: "structured-edit.js",
+          edits: [
+            {
+              oldText: [{ type: "text", text: "old" }],
+              newText: [{ kind: "text", value: "new" }],
+            },
+          ],
+        }),
+      ).rejects.toThrow(/Missing required parameter: edits/);
     } finally {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }

src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping-g.test.ts

@@ -27,7 +27,7 @@ function extractToolText(result: unknown): string {
 }
 
 describe("createOpenClawCodingTools read behavior", () => {
-  it("applies sandbox path guards to file_path alias", async () => {
+  it("applies sandbox path guards to canonical path", async () => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-sbx-"));
     const outsidePath = path.join(os.tmpdir(), "openclaw-outside.txt");
     await fs.writeFile(outsidePath, "outside", "utf8");
@@ -36,7 +36,7 @@ describe("createOpenClawCodingTools read behavior", () => {
         root: tmpDir,
         bridge: createHostSandboxFsBridge(tmpDir),
       });
-      await expect(readTool.execute("sandbox-1", { file_path: outsidePath })).rejects.toThrow(
+      await expect(readTool.execute("sandbox-1", { path: outsidePath })).rejects.toThrow(
         /sandbox root/i,
       );
     } finally {

src/agents/pi-tools.host-edit.ts

@@ -1,7 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 import type { AgentToolResult, AgentToolUpdateCallback } from "@mariozechner/pi-agent-core";
-import { normalizeToolParams } from "./pi-tools.params.js";
+import { getToolParamsRecord } from "./pi-tools.params.js";
 import type { AnyAgentTool } from "./pi-tools.types.js";
 
 type EditToolRecoveryOptions = {
@@ -61,12 +61,9 @@ function readEditReplacements(record: Record<string, unknown> | undefined): Edit
 }
 
 function readEditToolParams(params: unknown): EditToolParams {
-  const normalized = normalizeToolParams(params);
-  const record =
-    normalized ??
-    (params && typeof params === "object" ? (params as Record<string, unknown>) : undefined);
+  const record = getToolParamsRecord(params);
   return {
-    pathParam: readStringParam(record, "path", "file_path", "filePath", "file"),
+    pathParam: readStringParam(record, "path"),
     edits: readEditReplacements(record),
   };
 }