@codexa/cli 9.0.1 → 9.0.3

package/protocol/subagent-protocol.test.ts

@@ -0,0 +1,936 @@
+import { describe, it, expect } from "bun:test";
+import {
+  extractJsonFromText,
+  parseSubagentReturn,
+  formatValidationErrors,
+  type ParseResult,
+  type SubagentReturn,
+} from "./subagent-protocol";
+
+describe("extractJsonFromText", () => {
+  describe("JSON in code blocks", () => {
+    it("should extract JSON from json code block", () => {
+      const input = '```json\n{"status":"completed","summary":"ok"}\n```';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"ok"}');
+    });
+
+    it("should extract JSON from plain code block", () => {
+      const input = '```\n{"status":"completed","summary":"ok"}\n```';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"ok"}');
+    });
+
+    it("should handle code block with extra whitespace", () => {
+      const input = '```json\n\n  {"status":"completed"}  \n\n```';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed"}');
+    });
+  });
+
+  describe("Direct JSON objects", () => {
+    it("should extract direct JSON object", () => {
+      const input = '{"status":"completed","summary":"Task done"}';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"Task done"}');
+    });
+
+    it("should extract JSON object with whitespace", () => {
+      const input = '  \n{"status":"completed"}\n  ';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed"}');
+    });
+  });
+
+  describe("JSON with surrounding text", () => {
+    it("should extract JSON object from mixed text", () => {
+      const input = 'Here is my result: {"status":"completed","summary":"Done"} All finished.';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"Done"}');
+    });
+
+    it("should extract first valid JSON object containing status", () => {
+      const input = 'First: {"other":"data"} Second: {"status":"completed","summary":"ok"}';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"ok"}');
+    });
+
+    it("should handle nested braces in JSON", () => {
+      const input = 'Result: {"status":"completed","data":{"nested":"value"},"summary":"ok"}';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","data":{"nested":"value"},"summary":"ok"}');
+    });
+
+    it("should handle escaped quotes in strings", () => {
+      const input = '{"status":"completed","summary":"He said \\"hello\\""}';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"He said \\"hello\\""}');
+    });
+
+    it("should handle braces inside strings", () => {
+      const input = '{"status":"completed","summary":"Use {braces} like this"}';
+      const result = extractJsonFromText(input);
+      expect(result).toBe('{"status":"completed","summary":"Use {braces} like this"}');
+    });
+  });
+
+  describe("Invalid or missing JSON", () => {
+    it("should return null for plain text", () => {
+      const input = "Just plain text without JSON";
+      const result = extractJsonFromText(input);
+      expect(result).toBeNull();
+    });
+
+    it("should return trimmed text for brace-wrapped text without status", () => {
+      const input = "{not json at all}";
+      const result = extractJsonFromText(input);
+      // Falls back to trimmed text since it starts with { and ends with }
+      expect(result).toBe("{not json at all}");
+    });
+
+    it("should return null for JSON object without status key", () => {
+      const input = '{"other":"field","data":"value"}';
+      const result = extractJsonFromText(input);
+      // Should return trimmed since it starts with { and ends with }
+      expect(result).toBe('{"other":"field","data":"value"}');
+    });
+
+    it("should return null for empty string", () => {
+      const input = "";
+      const result = extractJsonFromText(input);
+      expect(result).toBeNull();
+    });
+
+    it("should return null for unclosed braces", () => {
+      const input = '{"status":"completed"';
+      const result = extractJsonFromText(input);
+      expect(result).toBeNull();
+    });
+  });
+});
+
+describe("parseSubagentReturn", () => {
+  describe("Valid returns", () => {
+    it("should parse valid minimal completed return", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Task completed successfully",
+        files_created: [],
+        files_modified: ["a.ts"],
+        reasoning: {
+          approach: "I analyzed the requirements and implemented the solution step by step",
+        },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.errors).toHaveLength(0);
+      expect(result.data).toBeDefined();
+      expect(result.data!.status).toBe("completed");
+      expect(result.data!.summary).toBe("Task completed successfully");
+      expect(result.data!.files_modified).toEqual(["a.ts"]);
+    });
+
+    it("should parse valid blocked return", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "Cannot proceed with implementation",
+        files_created: [],
+        files_modified: [],
+        blockers: ["Missing API key configuration"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.status).toBe("blocked");
+      expect(result.data!.blockers).toEqual(["Missing API key configuration"]);
+    });
+
+    it("should parse valid needs_decision return", () => {
+      const input = JSON.stringify({
+        status: "needs_decision",
+        summary: "Need guidance on approach",
+        files_created: [],
+        files_modified: [],
+        blockers: ["Which database migration strategy should we use?"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.status).toBe("needs_decision");
+      expect(result.data!.blockers).toEqual(["Which database migration strategy should we use?"]);
+    });
+
+    it("should parse return with all optional fields", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Implemented feature with patterns",
+        files_created: ["new.ts"],
+        files_modified: ["existing.ts"],
+        reasoning: {
+          approach: "Used factory pattern for extensibility and single responsibility",
+          challenges: ["Had to refactor legacy code"],
+          alternatives: ["Considered singleton pattern"],
+          recommendations: "Add more unit tests",
+        },
+        patterns_discovered: ["Factory pattern in auth"],
+        decisions_made: [
+          {
+            title: "Use TypeScript",
+            decision: "All new code in TS",
+            rationale: "Type safety",
+          },
+        ],
+        knowledge_to_broadcast: [
+          {
+            category: "pattern",
+            content: "Factory pattern used here",
+            severity: "info",
+          },
+        ],
+        utilities_created: [
+          {
+            name: "formatDate",
+            file: "utils/date.ts",
+            type: "function",
+            signature: "(date: Date) => string",
+            description: "Formats dates consistently",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.patterns_discovered).toEqual(["Factory pattern in auth"]);
+      expect(result.data!.decisions_made).toHaveLength(1);
+      expect(result.data!.knowledge_to_broadcast).toHaveLength(1);
+      expect(result.data!.utilities_created).toHaveLength(1);
+      expect(result.data!.reasoning!.challenges).toEqual(["Had to refactor legacy code"]);
+    });
+
+    it("should parse JSON in markdown code block", () => {
+      const input = `Here is the result:
+\`\`\`json
+{
+  "status": "completed",
+  "summary": "Feature implemented successfully",
+  "files_created": [],
+  "files_modified": ["app.ts"],
+  "reasoning": {
+    "approach": "Implemented the feature using existing patterns and added proper error handling"
+  }
+}
+\`\`\`
+Done!`;
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.status).toBe("completed");
+    });
+  });
+
+  describe("Default values", () => {
+    it("should default files_created to empty array if omitted", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "Cannot proceed",
+        blockers: ["Missing info"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.files_created).toEqual([]);
+    });
+
+    it("should default files_modified to empty array if omitted", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "Cannot proceed",
+        blockers: ["Missing info"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.files_modified).toEqual([]);
+    });
+  });
+
+  describe("Invalid status", () => {
+    it("should reject invalid status value", () => {
+      const input = JSON.stringify({
+        status: "invalid_status",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("status"))).toBe(true);
+    });
+
+    it("should reject missing status", () => {
+      const input = JSON.stringify({
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("status"))).toBe(true);
+    });
+  });
+
+  describe("Summary validation", () => {
+    it("should reject missing summary", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("summary"))).toBe(true);
+    });
+
+    it("should reject summary shorter than 10 characters", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Too short",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("summary") && e.includes("10"))).toBe(true);
+    });
+
+    it("should reject summary longer than 500 characters", () => {
+      const longSummary = "x".repeat(501);
+      const input = JSON.stringify({
+        status: "completed",
+        summary: longSummary,
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("summary") && e.includes("500"))).toBe(true);
+    });
+
+    it("should accept summary exactly 10 characters", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "1234567890",
+        files_created: [],
+        files_modified: [],
+        blockers: ["test"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("File arrays validation", () => {
+    it("should reject files_created as non-array", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: "not-an-array.ts",
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("files_created") && e.includes("array"))).toBe(true);
+    });
+
+    it("should reject files_modified as non-array", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: "not-an-array.ts",
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("files_modified") && e.includes("array"))).toBe(true);
+    });
+
+    it("should reject non-string elements in files_created", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: ["valid.ts", 123, "another.ts"],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("files_created[1]"))).toBe(true);
+    });
+  });
+
+  describe("Decisions validation", () => {
+    it("should reject decision missing title", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        decisions_made: [
+          {
+            decision: "Use React",
+            rationale: "Popular",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("decisions_made[0].title"))).toBe(true);
+    });
+
+    it("should reject decision missing decision field", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        decisions_made: [
+          {
+            title: "Framework choice",
+            rationale: "Popular",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("decisions_made[0].decision"))).toBe(true);
+    });
+
+    it("should accept valid decision with optional rationale", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Made a decision",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        decisions_made: [
+          {
+            title: "Framework",
+            decision: "Use React",
+            rationale: "Team expertise",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("Knowledge validation", () => {
+    it("should reject invalid knowledge category", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        knowledge_to_broadcast: [
+          {
+            category: "invalid_category",
+            content: "Some content",
+            severity: "info",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("knowledge_to_broadcast[0].category"))).toBe(true);
+    });
+
+    it("should reject invalid knowledge severity", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        knowledge_to_broadcast: [
+          {
+            category: "pattern",
+            content: "Some content",
+            severity: "invalid_severity",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("knowledge_to_broadcast[0].severity"))).toBe(true);
+    });
+
+    it("should reject knowledge with empty content", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        knowledge_to_broadcast: [
+          {
+            category: "pattern",
+            content: "",
+            severity: "info",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("knowledge_to_broadcast[0].content"))).toBe(true);
+    });
+
+    it("should accept all valid knowledge categories", () => {
+      const categories = ["discovery", "decision", "blocker", "pattern", "constraint"];
+
+      for (const category of categories) {
+        const input = JSON.stringify({
+          status: "completed",
+          summary: "Testing category",
+          files_created: [],
+          files_modified: [],
+          reasoning: { approach: "Did something good here" },
+          knowledge_to_broadcast: [
+            {
+              category,
+              content: "Test content",
+              severity: "info",
+            },
+          ],
+        });
+
+        const result = parseSubagentReturn(input);
+        expect(result.success).toBe(true);
+      }
+    });
+
+    it("should accept all valid severities", () => {
+      const severities = ["info", "warning", "critical"];
+
+      for (const severity of severities) {
+        const input = JSON.stringify({
+          status: "completed",
+          summary: "Testing severity",
+          files_created: [],
+          files_modified: [],
+          reasoning: { approach: "Did something good here" },
+          knowledge_to_broadcast: [
+            {
+              category: "pattern",
+              content: "Test content",
+              severity,
+            },
+          ],
+        });
+
+        const result = parseSubagentReturn(input);
+        expect(result.success).toBe(true);
+      }
+    });
+  });
+
+  describe("Reasoning validation", () => {
+    it("should reject completed status without reasoning", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("reasoning"))).toBe(true);
+    });
+
+    it("should reject completed status with reasoning but no approach", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: {
+          challenges: ["Some challenge"],
+        },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("reasoning.approach"))).toBe(true);
+    });
+
+    it("should reject completed status with approach shorter than 20 characters", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: {
+          approach: "Too short",
+        },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("reasoning.approach") && e.includes("20"))).toBe(true);
+    });
+
+    it("should accept completed status with valid reasoning", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Task completed well",
+        files_created: [],
+        files_modified: [],
+        reasoning: {
+          approach: "I analyzed the codebase and implemented a solution using existing patterns",
+        },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+
+    it("should accept reasoning with all optional fields", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Task completed well",
+        files_created: [],
+        files_modified: [],
+        reasoning: {
+          approach: "Used factory pattern for better extensibility and maintainability",
+          challenges: ["Refactoring legacy code", "Maintaining backwards compatibility"],
+          alternatives: ["Could have used singleton", "Considered dependency injection"],
+          recommendations: "Add integration tests for the new factory",
+        },
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.reasoning!.challenges).toHaveLength(2);
+      expect(result.data!.reasoning!.alternatives).toHaveLength(2);
+    });
+
+    it("should not require reasoning for blocked status", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "Cannot proceed",
+        files_created: [],
+        files_modified: [],
+        blockers: ["Missing configuration"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+
+    it("should not require reasoning for needs_decision status", () => {
+      const input = JSON.stringify({
+        status: "needs_decision",
+        summary: "Need guidance",
+        files_created: [],
+        files_modified: [],
+        blockers: ["Which approach to use?"],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("Utilities validation", () => {
+    it("should accept valid utilities_created", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Created utilities",
+        files_created: ["utils.ts"],
+        files_modified: [],
+        reasoning: { approach: "Created reusable utility functions for date handling" },
+        utilities_created: [
+          {
+            name: "formatDate",
+            file: "utils/date.ts",
+            type: "function",
+            signature: "(date: Date) => string",
+            description: "Formats dates",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+      expect(result.data!.utilities_created).toHaveLength(1);
+    });
+
+    it("should reject utilities_created with missing name", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        utilities_created: [
+          {
+            file: "utils.ts",
+            type: "function",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("utilities_created[0].name"))).toBe(true);
+    });
+
+    it("should reject utilities_created with missing file", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        utilities_created: [
+          {
+            name: "formatDate",
+            type: "function",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("utilities_created[0].file"))).toBe(true);
+    });
+
+    it("should accept utilities_created with only required fields", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "Created minimal utility",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        utilities_created: [
+          {
+            name: "helper",
+            file: "utils.ts",
+          },
+        ],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject utilities_created as non-array", () => {
+      const input = JSON.stringify({
+        status: "completed",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good here" },
+        utilities_created: "not-an-array",
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("utilities_created") && e.includes("array"))).toBe(true);
+    });
+  });
+
+  describe("Semantic validations", () => {
+    it("should require blockers for blocked status", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("blocked") && e.includes("blockers"))).toBe(true);
+    });
+
+    it("should require non-empty blockers for blocked status", () => {
+      const input = JSON.stringify({
+        status: "blocked",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        blockers: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("blocked") && e.includes("blockers"))).toBe(true);
+    });
+
+    it("should require blockers for needs_decision status", () => {
+      const input = JSON.stringify({
+        status: "needs_decision",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("needs_decision") && e.includes("blockers"))).toBe(true);
+    });
+
+    it("should require non-empty blockers for needs_decision status", () => {
+      const input = JSON.stringify({
+        status: "needs_decision",
+        summary: "This should fail",
+        files_created: [],
+        files_modified: [],
+        blockers: [],
+      });
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("needs_decision") && e.includes("blockers"))).toBe(true);
+    });
+  });
+
+  describe("No JSON found", () => {
+    it("should reject input with no JSON", () => {
+      const input = "Just plain text without any JSON structure";
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("Nenhum JSON encontrado"))).toBe(true);
+    });
+  });
+
+  describe("Invalid JSON", () => {
+    it("should reject malformed JSON", () => {
+      const input = '{"status": "completed", invalid json}';
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("JSON invalido"))).toBe(true);
+    });
+
+    it("should reject JSON with trailing comma", () => {
+      const input = '{"status": "completed", "summary": "test",}';
+
+      const result = parseSubagentReturn(input);
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("JSON invalido"))).toBe(true);
+    });
+  });
+});
+
+describe("formatValidationErrors", () => {
+  it("should return empty string for successful result", () => {
+    const result: ParseResult = {
+      success: true,
+      data: {
+        status: "completed",
+        summary: "Task completed",
+        files_created: [],
+        files_modified: [],
+        reasoning: { approach: "Did something good" },
+      },
+      errors: [],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toBe("");
+  });
+
+  it("should format single error", () => {
+    const result: ParseResult = {
+      success: false,
+      errors: ["Campo 'status' invalido"],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toContain("ERRO: Retorno do subagent INVALIDO");
+    expect(formatted).toContain("Campo 'status' invalido");
+  });
+
+  it("should format multiple errors", () => {
+    const result: ParseResult = {
+      success: false,
+      errors: [
+        "Campo 'status' invalido",
+        "Campo 'summary' deve ter pelo menos 10 caracteres",
+        "Status 'blocked' requer campo 'blockers' nao vazio",
+      ],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toContain("Campo 'status' invalido");
+    expect(formatted).toContain("Campo 'summary' deve ter pelo menos 10 caracteres");
+    expect(formatted).toContain("Status 'blocked' requer campo 'blockers' nao vazio");
+  });
+
+  it("should include protocol example in output", () => {
+    const result: ParseResult = {
+      success: false,
+      errors: ["Some error"],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toContain("O retorno deve seguir o formato:");
+    expect(formatted).toContain('"status": "completed | blocked | needs_decision"');
+    expect(formatted).toContain('"reasoning"');
+  });
+
+  it("should include separator lines", () => {
+    const result: ParseResult = {
+      success: false,
+      errors: ["Error 1", "Error 2"],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toContain("─".repeat(50));
+  });
+
+  it("should format each error with bullet point", () => {
+    const result: ParseResult = {
+      success: false,
+      errors: ["First error", "Second error"],
+      rawInput: "{}",
+    };
+
+    const formatted = formatValidationErrors(result);
+    expect(formatted).toContain("  - First error");
+    expect(formatted).toContain("  - Second error");
+  });
+});