@codexa/cli 8.5.0 → 8.6.0

package/protocol/subagent-protocol.ts

@@ -1,412 +1,402 @@
-/**
- * Subagent Protocol Parser & Validator
- *
- * Este modulo GARANTE que todos os retornos de subagents sigam o protocolo definido.
- * Sem validacao correta, task done NAO pode ser executado.
- */
-
-// Tipos do protocolo
-export interface Decision {
-  title: string;
-  decision: string;
-  rationale?: string;
-}
-
-export interface Knowledge {
-  category: "discovery" | "decision" | "blocker" | "pattern" | "constraint";
-  content: string;
-  severity: "info" | "warning" | "critical";
-}
-
-// v8.0: Raciocínio do subagent
-export interface Reasoning {
-  approach: string;           // Como abordou o problema
-  challenges?: string[];      // Desafios encontrados
-  alternatives?: string[];    // Alternativas consideradas
-  recommendations?: string;   // Recomendações para próximas tasks
-}
-
-export interface SubagentReturn {
-  status: "completed" | "blocked" | "needs_decision";
-  summary: string;
-  files_created: string[];
-  files_modified: string[];
-  patterns_discovered?: string[];
-  decisions_made?: Decision[];
-  blockers?: string[];
-  knowledge_to_broadcast?: Knowledge[];
-  // v8.0: Campos de raciocínio (recomendados mas não obrigatórios por compatibilidade)
-  reasoning?: Reasoning;
-  // v8.5: Utilities criadas/exportadas nesta task (DRY enforcement)
-  utilities_created?: Array<{
-    name: string;
-    file: string;
-    type?: string;
-    signature?: string;
-    description?: string;
-  }>;
-}
-
-export interface ParseResult {
-  success: boolean;
-  data?: SubagentReturn;
-  errors: string[];
-  rawInput: string;
-}
-
-const VALID_STATUSES = ["completed", "blocked", "needs_decision"];
-const VALID_KNOWLEDGE_CATEGORIES = ["discovery", "decision", "blocker", "pattern", "constraint"];
-const VALID_SEVERITIES = ["info", "warning", "critical"];
-
-/**
- * Extrai JSON de uma string que pode conter texto misto
- * Subagents podem retornar texto com JSON embutido
- */
-function extractJsonFromText(text: string): string | null {
-  // Tenta encontrar JSON em bloco de codigo
-  const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
-  if (codeBlockMatch) {
-    return codeBlockMatch[1].trim();
-  }
-
-  // Tenta encontrar objeto JSON direto (busca mais robusta)
-  // Procura por { ... "status" ... } capturando todo o objeto
-  let depth = 0;
-  let start = -1;
-  let inString = false;
-  let escape = false;
-
-  for (let i = 0; i < text.length; i++) {
-    const char = text[i];
-
-    if (escape) {
-      escape = false;
-      continue;
-    }
-
-    if (char === "\\") {
-      escape = true;
-      continue;
-    }
-
-    if (char === '"' && !escape) {
-      inString = !inString;
-      continue;
-    }
-
-    if (inString) continue;
-
-    if (char === "{") {
-      if (depth === 0) start = i;
-      depth++;
-    } else if (char === "}") {
-      depth--;
-      if (depth === 0 && start !== -1) {
-        const candidate = text.slice(start, i + 1);
-        if (candidate.includes('"status"')) {
-          return candidate;
-        }
-        start = -1;
-      }
-    }
-  }
-
-  // Se o texto inteiro parece ser JSON
-  const trimmed = text.trim();
-  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
-    return trimmed;
-  }
-
-  return null;
-}
-
-/**
- * Valida um campo string
- */
-function validateString(value: unknown, field: string, minLen = 0, maxLen = Infinity): string | null {
-  if (typeof value !== "string") {
-    return `Campo '${field}' deve ser string`;
-  }
-  if (value.length < minLen) {
-    return `Campo '${field}' deve ter pelo menos ${minLen} caracteres`;
-  }
-  if (value.length > maxLen) {
-    return `Campo '${field}' deve ter no maximo ${maxLen} caracteres`;
-  }
-  return null;
-}
-
-/**
- * Valida um array de strings
- */
-function validateStringArray(value: unknown, field: string): string | null {
-  if (!Array.isArray(value)) {
-    return `Campo '${field}' deve ser um array`;
-  }
-  for (let i = 0; i < value.length; i++) {
-    if (typeof value[i] !== "string") {
-      return `Campo '${field}[${i}]' deve ser string`;
-    }
-  }
-  return null;
-}
-
-/**
- * Valida uma decision
- */
-function validateDecision(value: unknown, index: number): string[] {
-  const errors: string[] = [];
-  if (typeof value !== "object" || value === null) {
-    return [`decisions_made[${index}] deve ser um objeto`];
-  }
-  const dec = value as Record<string, unknown>;
-
-  if (typeof dec.title !== "string" || dec.title.length === 0) {
-    errors.push(`decisions_made[${index}].title obrigatorio`);
-  }
-  if (typeof dec.decision !== "string" || dec.decision.length === 0) {
-    errors.push(`decisions_made[${index}].decision obrigatorio`);
-  }
-  return errors;
-}
-
-/**
- * Valida um knowledge
- */
-function validateKnowledge(value: unknown, index: number): string[] {
-  const errors: string[] = [];
-  if (typeof value !== "object" || value === null) {
-    return [`knowledge_to_broadcast[${index}] deve ser um objeto`];
-  }
-  const k = value as Record<string, unknown>;
-
-  if (!VALID_KNOWLEDGE_CATEGORIES.includes(k.category as string)) {
-    errors.push(`knowledge_to_broadcast[${index}].category invalido. Use: ${VALID_KNOWLEDGE_CATEGORIES.join(", ")}`);
-  }
-  if (typeof k.content !== "string" || k.content.length === 0) {
-    errors.push(`knowledge_to_broadcast[${index}].content obrigatorio`);
-  }
-  if (!VALID_SEVERITIES.includes(k.severity as string)) {
-    errors.push(`knowledge_to_broadcast[${index}].severity invalido. Use: ${VALID_SEVERITIES.join(", ")}`);
-  }
-  return errors;
-}
-
-/**
- * Parse e valida o retorno de um subagent
- */
-export function parseSubagentReturn(input: string): ParseResult {
-  const errors: string[] = [];
-
-  // 1. Extrair JSON do input
-  const jsonStr = extractJsonFromText(input);
-  if (!jsonStr) {
-    return {
-      success: false,
-      errors: [
-        "Nenhum JSON encontrado no retorno do subagent.",
-        "O subagent DEVE retornar um objeto JSON no formato especificado em PROTOCOL.md.",
-        "Formatos aceitos: JSON puro, ou JSON em bloco ```json```",
-      ],
-      rawInput: input,
-    };
-  }
-
-  // 2. Parse JSON
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(jsonStr);
-  } catch (e) {
-    return {
-      success: false,
-      errors: [
-        `JSON invalido: ${(e as Error).message}`,
-        "Verifique se o JSON esta bem formatado.",
-      ],
-      rawInput: input,
-    };
-  }
-
-  // 3. Validar campos obrigatorios
-
-  // status
-  if (!VALID_STATUSES.includes(parsed.status as string)) {
-    errors.push(`Campo 'status' invalido. Use: ${VALID_STATUSES.join(", ")}`);
-  }
-
-  // summary
-  const summaryError = validateString(parsed.summary, "summary", 10, 500);
-  if (summaryError) errors.push(summaryError);
-
-  // files_created
-  const filesCreatedError = validateStringArray(parsed.files_created, "files_created");
-  if (filesCreatedError) errors.push(filesCreatedError);
-
-  // files_modified
-  const filesModifiedError = validateStringArray(parsed.files_modified, "files_modified");
-  if (filesModifiedError) errors.push(filesModifiedError);
-
-  // 4. Validar campos opcionais se presentes
-
-  // patterns_discovered
-  if (parsed.patterns_discovered !== undefined) {
-    const patternsError = validateStringArray(parsed.patterns_discovered, "patterns_discovered");
-    if (patternsError) errors.push(patternsError);
-  }
-
-  // blockers
-  if (parsed.blockers !== undefined) {
-    const blockersError = validateStringArray(parsed.blockers, "blockers");
-    if (blockersError) errors.push(blockersError);
-  }
-
-  // decisions_made
-  if (parsed.decisions_made !== undefined) {
-    if (!Array.isArray(parsed.decisions_made)) {
-      errors.push("Campo 'decisions_made' deve ser um array");
-    } else {
-      for (let i = 0; i < parsed.decisions_made.length; i++) {
-        errors.push(...validateDecision(parsed.decisions_made[i], i));
-      }
-    }
-  }
-
-  // knowledge_to_broadcast
-  if (parsed.knowledge_to_broadcast !== undefined) {
-    if (!Array.isArray(parsed.knowledge_to_broadcast)) {
-      errors.push("Campo 'knowledge_to_broadcast' deve ser um array");
-    } else {
-      for (let i = 0; i < parsed.knowledge_to_broadcast.length; i++) {
-        errors.push(...validateKnowledge(parsed.knowledge_to_broadcast[i], i));
-      }
-    }
-  }
-
-  // v8.0: reasoning (opcional, mas validar estrutura se presente)
-  if (parsed.reasoning !== undefined) {
-    if (typeof parsed.reasoning !== "object" || parsed.reasoning === null) {
-      errors.push("Campo 'reasoning' deve ser um objeto");
-    } else {
-      const r = parsed.reasoning as Record<string, unknown>;
-      if (r.approach !== undefined && typeof r.approach !== "string") {
-        errors.push("Campo 'reasoning.approach' deve ser string");
-      }
-      if (r.challenges !== undefined) {
-        const challengesError = validateStringArray(r.challenges, "reasoning.challenges");
-        if (challengesError) errors.push(challengesError);
-      }
-      if (r.alternatives !== undefined) {
-        const alternativesError = validateStringArray(r.alternatives, "reasoning.alternatives");
-        if (alternativesError) errors.push(alternativesError);
-      }
-      if (r.recommendations !== undefined && typeof r.recommendations !== "string") {
-        errors.push("Campo 'reasoning.recommendations' deve ser string");
-      }
-    }
-  }
-
-  // v8.5: utilities_created (opcional, validar estrutura se presente)
-  if (parsed.utilities_created !== undefined) {
-    if (!Array.isArray(parsed.utilities_created)) {
-      errors.push("Campo 'utilities_created' deve ser um array");
-    } else {
-      for (let i = 0; i < parsed.utilities_created.length; i++) {
-        const u = parsed.utilities_created[i] as any;
-        if (!u || typeof u !== "object") {
-          errors.push(`utilities_created[${i}] deve ser um objeto`);
-          continue;
-        }
-        if (typeof u.name !== "string" || u.name.length === 0) {
-          errors.push(`utilities_created[${i}].name obrigatorio`);
-        }
-        if (typeof u.file !== "string" || u.file.length === 0) {
-          errors.push(`utilities_created[${i}].file obrigatorio`);
-        }
-      }
-    }
-  }
-
-  // 5. Validacoes semanticas
-
-  // Se blocked, deve ter blockers
-  if (parsed.status === "blocked") {
-    if (!parsed.blockers || !Array.isArray(parsed.blockers) || parsed.blockers.length === 0) {
-      errors.push("Status 'blocked' requer campo 'blockers' nao vazio");
-    }
-  }
-
-  // Se needs_decision, deve ter blockers descrevendo a decisao
-  if (parsed.status === "needs_decision") {
-    if (!parsed.blockers || !Array.isArray(parsed.blockers) || parsed.blockers.length === 0) {
-      errors.push("Status 'needs_decision' requer campo 'blockers' descrevendo a decisao necessaria");
-    }
-  }
-
-  if (errors.length > 0) {
-    return {
-      success: false,
-      errors,
-      rawInput: input,
-    };
-  }
-
-  // Cast para tipo correto
-  const data: SubagentReturn = {
-    status: parsed.status as SubagentReturn["status"],
-    summary: parsed.summary as string,
-    files_created: parsed.files_created as string[],
-    files_modified: parsed.files_modified as string[],
-    patterns_discovered: parsed.patterns_discovered as string[] | undefined,
-    decisions_made: parsed.decisions_made as Decision[] | undefined,
-    blockers: parsed.blockers as string[] | undefined,
-    knowledge_to_broadcast: parsed.knowledge_to_broadcast as Knowledge[] | undefined,
-    reasoning: parsed.reasoning as Reasoning | undefined,
-    utilities_created: parsed.utilities_created as SubagentReturn["utilities_created"],
-  };
-
-  return {
-    success: true,
-    data,
-    errors: [],
-    rawInput: input,
-  };
-}
-
-/**
- * Formata erros de validacao para exibicao
- */
-export function formatValidationErrors(result: ParseResult): string {
-  if (result.success) return "";
-
-  let output = "\n[X] ERRO: Retorno do subagent INVALIDO\n";
-  output += "─".repeat(50) + "\n\n";
-
-  for (const error of result.errors) {
-    output += `  - ${error}\n`;
-  }
-
-  output += "\n" + "─".repeat(50) + "\n";
-  output += "O retorno deve seguir o formato:\n\n";
-  output += `{
-  "status": "completed | blocked | needs_decision",
-  "summary": "Resumo do que foi feito (10-500 chars)",
-  "files_created": ["path/to/file.ts"],
-  "files_modified": ["path/to/other.ts"],
-  "patterns_discovered": ["Pattern identificado"],
-  "decisions_made": [{"title": "...", "decision": "..."}],
-  "blockers": ["Bloqueio se status != completed"],
-  "knowledge_to_broadcast": [{"category": "...", "content": "...", "severity": "..."}]
-}\n`;
-
-  return output;
-}
-
-/**
- * Verifica se uma string parece conter um retorno de subagent
- */
-export function looksLikeSubagentReturn(text: string): boolean {
-  return text.includes('"status"') &&
-    (text.includes('"completed"') ||
-      text.includes('"blocked"') ||
-      text.includes('"needs_decision"'));
+/**
+ * Subagent Protocol Parser & Validator
+ *
+ * Este modulo GARANTE que todos os retornos de subagents sigam o protocolo definido.
+ * Sem validacao correta, task done NAO pode ser executado.
+ */
+
+// Tipos do protocolo
+export interface Decision {
+  title: string;
+  decision: string;
+  rationale?: string;
+}
+
+export interface Knowledge {
+  category: "discovery" | "decision" | "blocker" | "pattern" | "constraint";
+  content: string;
+  severity: "info" | "warning" | "critical";
+}
+
+// v8.0: Raciocínio do subagent
+export interface Reasoning {
+  approach: string;           // Como abordou o problema
+  challenges?: string[];      // Desafios encontrados
+  alternatives?: string[];    // Alternativas consideradas
+  recommendations?: string;   // Recomendações para próximas tasks
+}
+
+export interface SubagentReturn {
+  status: "completed" | "blocked" | "needs_decision";
+  summary: string;
+  files_created: string[];
+  files_modified: string[];
+  patterns_discovered?: string[];
+  decisions_made?: Decision[];
+  blockers?: string[];
+  knowledge_to_broadcast?: Knowledge[];
+  // v8.0: Campos de raciocínio (recomendados mas não obrigatórios por compatibilidade)
+  reasoning?: Reasoning;
+  // v8.5: Utilities criadas/exportadas nesta task (DRY enforcement)
+  utilities_created?: Array<{
+    name: string;
+    file: string;
+    type?: string;
+    signature?: string;
+    description?: string;
+  }>;
+}
+
+export interface ParseResult {
+  success: boolean;
+  data?: SubagentReturn;
+  errors: string[];
+  rawInput: string;
+}
+
+const VALID_STATUSES = ["completed", "blocked", "needs_decision"];
+const VALID_KNOWLEDGE_CATEGORIES = ["discovery", "decision", "blocker", "pattern", "constraint"];
+const VALID_SEVERITIES = ["info", "warning", "critical"];
+
+/**
+ * Extrai JSON de uma string que pode conter texto misto
+ * Subagents podem retornar texto com JSON embutido
+ */
+function extractJsonFromText(text: string): string | null {
+  // Tenta encontrar JSON em bloco de codigo
+  const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (codeBlockMatch) {
+    return codeBlockMatch[1].trim();
+  }
+
+  // Tenta encontrar objeto JSON direto (busca mais robusta)
+  // Procura por { ... "status" ... } capturando todo o objeto
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escape = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+
+    if (escape) {
+      escape = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escape = true;
+      continue;
+    }
+
+    if (char === '"' && !escape) {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) continue;
+
+    if (char === "{") {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (char === "}") {
+      depth--;
+      if (depth === 0 && start !== -1) {
+        const candidate = text.slice(start, i + 1);
+        if (candidate.includes('"status"')) {
+          return candidate;
+        }
+        start = -1;
+      }
+    }
+  }
+
+  // Se o texto inteiro parece ser JSON
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    return trimmed;
+  }
+
+  return null;
+}
+
+/**
+ * Valida um campo string
+ */
+function validateString(value: unknown, field: string, minLen = 0, maxLen = Infinity): string | null {
+  if (typeof value !== "string") {
+    return `Campo '${field}' deve ser string`;
+  }
+  if (value.length < minLen) {
+    return `Campo '${field}' deve ter pelo menos ${minLen} caracteres`;
+  }
+  if (value.length > maxLen) {
+    return `Campo '${field}' deve ter no maximo ${maxLen} caracteres`;
+  }
+  return null;
+}
+
+/**
+ * Valida um array de strings
+ */
+function validateStringArray(value: unknown, field: string): string | null {
+  if (!Array.isArray(value)) {
+    return `Campo '${field}' deve ser um array`;
+  }
+  for (let i = 0; i < value.length; i++) {
+    if (typeof value[i] !== "string") {
+      return `Campo '${field}[${i}]' deve ser string`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Valida uma decision
+ */
+function validateDecision(value: unknown, index: number): string[] {
+  const errors: string[] = [];
+  if (typeof value !== "object" || value === null) {
+    return [`decisions_made[${index}] deve ser um objeto`];
+  }
+  const dec = value as Record<string, unknown>;
+
+  if (typeof dec.title !== "string" || dec.title.length === 0) {
+    errors.push(`decisions_made[${index}].title obrigatorio`);
+  }
+  if (typeof dec.decision !== "string" || dec.decision.length === 0) {
+    errors.push(`decisions_made[${index}].decision obrigatorio`);
+  }
+  return errors;
+}
+
+/**
+ * Valida um knowledge
+ */
+function validateKnowledge(value: unknown, index: number): string[] {
+  const errors: string[] = [];
+  if (typeof value !== "object" || value === null) {
+    return [`knowledge_to_broadcast[${index}] deve ser um objeto`];
+  }
+  const k = value as Record<string, unknown>;
+
+  if (!VALID_KNOWLEDGE_CATEGORIES.includes(k.category as string)) {
+    errors.push(`knowledge_to_broadcast[${index}].category invalido. Use: ${VALID_KNOWLEDGE_CATEGORIES.join(", ")}`);
+  }
+  if (typeof k.content !== "string" || k.content.length === 0) {
+    errors.push(`knowledge_to_broadcast[${index}].content obrigatorio`);
+  }
+  if (!VALID_SEVERITIES.includes(k.severity as string)) {
+    errors.push(`knowledge_to_broadcast[${index}].severity invalido. Use: ${VALID_SEVERITIES.join(", ")}`);
+  }
+  return errors;
+}
+
+/**
+ * Parse e valida o retorno de um subagent
+ */
+export function parseSubagentReturn(input: string): ParseResult {
+  const errors: string[] = [];
+
+  // 1. Extrair JSON do input
+  const jsonStr = extractJsonFromText(input);
+  if (!jsonStr) {
+    return {
+      success: false,
+      errors: [
+        "Nenhum JSON encontrado no retorno do subagent.",
+        "O subagent DEVE retornar um objeto JSON no formato especificado em PROTOCOL.md.",
+        "Formatos aceitos: JSON puro, ou JSON em bloco ```json```",
+      ],
+      rawInput: input,
+    };
+  }
+
+  // 2. Parse JSON
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch (e) {
+    return {
+      success: false,
+      errors: [
+        `JSON invalido: ${(e as Error).message}`,
+        "Verifique se o JSON esta bem formatado.",
+      ],
+      rawInput: input,
+    };
+  }
+
+  // 3. Validar campos obrigatorios
+
+  // status
+  if (!VALID_STATUSES.includes(parsed.status as string)) {
+    errors.push(`Campo 'status' invalido. Use: ${VALID_STATUSES.join(", ")}`);
+  }
+
+  // summary
+  const summaryError = validateString(parsed.summary, "summary", 10, 500);
+  if (summaryError) errors.push(summaryError);
+
+  // files_created
+  const filesCreatedError = validateStringArray(parsed.files_created, "files_created");
+  if (filesCreatedError) errors.push(filesCreatedError);
+
+  // files_modified
+  const filesModifiedError = validateStringArray(parsed.files_modified, "files_modified");
+  if (filesModifiedError) errors.push(filesModifiedError);
+
+  // 4. Validar campos opcionais se presentes
+
+  // patterns_discovered
+  if (parsed.patterns_discovered !== undefined) {
+    const patternsError = validateStringArray(parsed.patterns_discovered, "patterns_discovered");
+    if (patternsError) errors.push(patternsError);
+  }
+
+  // blockers
+  if (parsed.blockers !== undefined) {
+    const blockersError = validateStringArray(parsed.blockers, "blockers");
+    if (blockersError) errors.push(blockersError);
+  }
+
+  // decisions_made
+  if (parsed.decisions_made !== undefined) {
+    if (!Array.isArray(parsed.decisions_made)) {
+      errors.push("Campo 'decisions_made' deve ser um array");
+    } else {
+      for (let i = 0; i < parsed.decisions_made.length; i++) {
+        errors.push(...validateDecision(parsed.decisions_made[i], i));
+      }
+    }
+  }
+
+  // knowledge_to_broadcast
+  if (parsed.knowledge_to_broadcast !== undefined) {
+    if (!Array.isArray(parsed.knowledge_to_broadcast)) {
+      errors.push("Campo 'knowledge_to_broadcast' deve ser um array");
+    } else {
+      for (let i = 0; i < parsed.knowledge_to_broadcast.length; i++) {
+        errors.push(...validateKnowledge(parsed.knowledge_to_broadcast[i], i));
+      }
+    }
+  }
+
+  // v8.0: reasoning (opcional, mas validar estrutura se presente)
+  if (parsed.reasoning !== undefined) {
+    if (typeof parsed.reasoning !== "object" || parsed.reasoning === null) {
+      errors.push("Campo 'reasoning' deve ser um objeto");
+    } else {
+      const r = parsed.reasoning as Record<string, unknown>;
+      if (r.approach !== undefined && typeof r.approach !== "string") {
+        errors.push("Campo 'reasoning.approach' deve ser string");
+      }
+      if (r.challenges !== undefined) {
+        const challengesError = validateStringArray(r.challenges, "reasoning.challenges");
+        if (challengesError) errors.push(challengesError);
+      }
+      if (r.alternatives !== undefined) {
+        const alternativesError = validateStringArray(r.alternatives, "reasoning.alternatives");
+        if (alternativesError) errors.push(alternativesError);
+      }
+      if (r.recommendations !== undefined && typeof r.recommendations !== "string") {
+        errors.push("Campo 'reasoning.recommendations' deve ser string");
+      }
+    }
+  }
+
+  // v8.5: utilities_created (opcional, validar estrutura se presente)
+  if (parsed.utilities_created !== undefined) {
+    if (!Array.isArray(parsed.utilities_created)) {
+      errors.push("Campo 'utilities_created' deve ser um array");
+    } else {
+      for (let i = 0; i < parsed.utilities_created.length; i++) {
+        const u = parsed.utilities_created[i] as any;
+        if (!u || typeof u !== "object") {
+          errors.push(`utilities_created[${i}] deve ser um objeto`);
+          continue;
+        }
+        if (typeof u.name !== "string" || u.name.length === 0) {
+          errors.push(`utilities_created[${i}].name obrigatorio`);
+        }
+        if (typeof u.file !== "string" || u.file.length === 0) {
+          errors.push(`utilities_created[${i}].file obrigatorio`);
+        }
+      }
+    }
+  }
+
+  // 5. Validacoes semanticas
+
+  // Se blocked, deve ter blockers
+  if (parsed.status === "blocked") {
+    if (!parsed.blockers || !Array.isArray(parsed.blockers) || parsed.blockers.length === 0) {
+      errors.push("Status 'blocked' requer campo 'blockers' nao vazio");
+    }
+  }
+
+  // Se needs_decision, deve ter blockers descrevendo a decisao
+  if (parsed.status === "needs_decision") {
+    if (!parsed.blockers || !Array.isArray(parsed.blockers) || parsed.blockers.length === 0) {
+      errors.push("Status 'needs_decision' requer campo 'blockers' descrevendo a decisao necessaria");
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      success: false,
+      errors,
+      rawInput: input,
+    };
+  }
+
+  // Cast para tipo correto
+  const data: SubagentReturn = {
+    status: parsed.status as SubagentReturn["status"],
+    summary: parsed.summary as string,
+    files_created: parsed.files_created as string[],
+    files_modified: parsed.files_modified as string[],
+    patterns_discovered: parsed.patterns_discovered as string[] | undefined,
+    decisions_made: parsed.decisions_made as Decision[] | undefined,
+    blockers: parsed.blockers as string[] | undefined,
+    knowledge_to_broadcast: parsed.knowledge_to_broadcast as Knowledge[] | undefined,
+    reasoning: parsed.reasoning as Reasoning | undefined,
+    utilities_created: parsed.utilities_created as SubagentReturn["utilities_created"],
+  };
+
+  return {
+    success: true,
+    data,
+    errors: [],
+    rawInput: input,
+  };
+}
+
+/**
+ * Formata erros de validacao para exibicao
+ */
+export function formatValidationErrors(result: ParseResult): string {
+  if (result.success) return "";
+
+  let output = "\n[X] ERRO: Retorno do subagent INVALIDO\n";
+  output += "─".repeat(50) + "\n\n";
+
+  for (const error of result.errors) {
+    output += `  - ${error}\n`;
+  }
+
+  output += "\n" + "─".repeat(50) + "\n";
+  output += "O retorno deve seguir o formato:\n\n";
+  output += `{
+  "status": "completed | blocked | needs_decision",
+  "summary": "Resumo do que foi feito (10-500 chars)",
+  "files_created": ["path/to/file.ts"],
+  "files_modified": ["path/to/other.ts"],
+  "patterns_discovered": ["Pattern identificado"],
+  "decisions_made": [{"title": "...", "decision": "..."}],
+  "blockers": ["Bloqueio se status != completed"],
+  "knowledge_to_broadcast": [{"category": "...", "content": "...", "severity": "..."}]
+}\n`;
+
+  return output;
 }