fix: strip hallucinated args from tool calls to prevent retry loops

Claude models sometimes hallucinate extra arguments (e.g. limit,
content_search_mode) that fail schema validation and cause infinite
retry storms. Strip unknown top-level properties when schema has
additionalProperties: false, log stripped args, and append a feedback
note to the tool result so the model learns not to retry with them.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: harryblam

src/handlers/useTool.ts

@@ -120,8 +120,9 @@ export async function handleUseTool(
   }
 
   // Validate arguments unconditionally (before checking dry_run)
+  let strippedArgs: string[] = [];
   try {
-    validator.validate(schema, args, { package_id, tool_id });
+    strippedArgs = validator.validate(schema, args, { package_id, tool_id });
   } catch (error) {
     if (error instanceof ValidationError) {
       let helpMessage = `Argument validation failed for tool '${tool_id}' in package '${package_id}'.\n`;
@@ -171,11 +172,16 @@ export async function handleUseTool(
       telemetry: { duration_ms: 0, status: "ok" },
     };
 
+    let dryRunJson = JSON.stringify(result, null, 2);
+    if (strippedArgs.length > 0) {
+      dryRunJson += `\n\nNote: Removed unknown arguments before validation: ${strippedArgs.join(', ')}. These are not valid for this tool.`;
+    }
+
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify(result, null, 2),
+          text: dryRunJson,
         },
       ],
       isError: false,
@@ -235,6 +241,10 @@ export async function handleUseTool(
       outputJson = JSON.stringify(result, null, 2);
     }
 
+    if (strippedArgs.length > 0) {
+      outputJson += `\n\nNote: Removed unknown arguments before execution: ${strippedArgs.join(', ')}. These are not valid for this tool.`;
+    }
+
     return {
       content: [
         {

src/validator.ts

@@ -31,7 +31,10 @@ export class Validator {
     addFormats(this.ajv);
   }
 
-  validate(schema: any, data: any, context?: { package_id?: string; tool_id?: string }): void {
+  /** Validates data against schema. Mutates `data` in place to strip unknown
+   *  top-level properties when `additionalProperties: false`. Returns names of
+   *  any stripped properties (empty array if none). */
+  validate(schema: any, data: any, context?: { package_id?: string; tool_id?: string }): string[] {
     logger.debug("Validating arguments", {
       package_id: context?.package_id,
       tool_id: context?.tool_id,
@@ -43,6 +46,32 @@ export class Validator {
       throw new ValidationError("Schema is required", []);
     }
 
+    // Strip unknown top-level properties when schema forbids them.
+    // Claude models sometimes hallucinate extra args (e.g. "limit") that cause
+    // validation failures and retry loops. We strip and log rather than reject.
+    const strippedArgs: string[] = [];
+    if (
+      schema.additionalProperties === false &&
+      schema.properties &&
+      typeof data === 'object' &&
+      data !== null
+    ) {
+      const allowed = new Set(Object.keys(schema.properties));
+      for (const key of Object.keys(data)) {
+        if (!allowed.has(key)) {
+          strippedArgs.push(key);
+          delete data[key];
+        }
+      }
+      if (strippedArgs.length > 0) {
+        logger.warn("Stripped unknown properties from tool args", {
+          package_id: context?.package_id,
+          tool_id: context?.tool_id,
+          stripped: strippedArgs,
+        });
+      }
+    }
+
     // Compile schema with better error handling for format issues
     let validate;
     try {
@@ -83,6 +112,8 @@ export class Validator {
       package_id: context?.package_id,
       tool_id: context?.tool_id,
     });
+
+    return strippedArgs;
   }
 }