refactor(subagents): add Zod validation to message passing (Priority 2)

Following TypeScript Standards Rule #2: No Type Assertions Without Validation

Changes:
- Created message schemas (packages/subagents/src/schemas/messages.ts)
  * PlanningRequestSchema for planner agent
  * ExplorationRequestSchema (discriminated union) for explorer agent
  * GitHubContextRequestSchema for GitHub agent
  * 22 comprehensive tests with 100% coverage

- Replaced 3 type assertions with validated functions:
  * planner/index.ts: validatePlanningRequest()
  * explorer/index.ts: validateExplorationRequest()
  * github/agent.ts: validateGitHubContextRequest()

- Updated 3 tests to expect 'error' messages for invalid requests
  * planner/__tests__/index.test.ts
  * explorer/__tests__/index.test.ts
  * coordinator/__tests__/coordinator.integration.test.ts

Impact:
- Zero type assertions in inter-agent communication (MEDIUM RISK boundary)
- Better error messages: 'Invalid planning request: issueNumber: ...'
- Bulletproof against malformed coordinator messages
- All 1739 tests passing ✅

Scope: Inter-agent message validation

Author: prosdev

packages/subagents/src/coordinator/__tests__/coordinator.integration.test.ts

@@ -186,11 +186,11 @@ describe('Coordinator → Explorer Integration', () => {
       });
 
       expect(response).toBeDefined();
-      expect(response?.type).toBe('response');
+      expect(response?.type).toBe('error');
 
       const result = response?.payload as { error?: string };
       expect(result.error).toBeDefined();
-      expect(result.error).toContain('Unknown action');
+      expect(result.error).toContain('Invalid exploration request');
     });
 
     it('should handle non-existent agent gracefully', async () => {

packages/subagents/src/explorer/__tests__/index.test.ts

@@ -579,10 +579,11 @@ describe('ExplorerAgent', () => {
       const response = await explorer.handleMessage(message);
 
       expect(response).toBeDefined();
-      expect(response?.type).toBe('response');
+      expect(response?.type).toBe('error');
 
       const result = response?.payload as { error?: string };
       expect(result.error).toBeDefined();
+      expect(result.error).toContain('Invalid exploration request');
     });
 
     it('should return error response on failure', async () => {

packages/subagents/src/explorer/index.ts

@@ -3,6 +3,7 @@
  * Explores and analyzes code patterns using semantic search
  */
 
+import { validateExplorationRequest } from '../schemas/messages.js';
 import type { Agent, AgentContext, Message } from '../types';
 import type {
   CodeInsights,
@@ -53,7 +54,7 @@ export class ExplorerAgent implements Agent {
     }
 
     try {
-      const request = message.payload as unknown as ExplorationRequest;
+      const request = validateExplorationRequest(message.payload);
       logger.debug('Processing exploration request', { action: request.action });
 
       let result: ExplorationResult | ExplorationError;

packages/subagents/src/github/agent.ts

@@ -3,6 +3,7 @@
  * Provides rich context from GitHub issues, PRs, and discussions
  */
 
+import { validateGitHubContextRequest } from '../schemas/messages.js';
 import type { Agent, AgentContext, Message } from '../types';
 import { GitHubIndexer } from './indexer';
 import type {
@@ -67,7 +68,7 @@ export class GitHubAgent implements Agent {
     }
 
     try {
-      const request = message.payload as unknown as GitHubContextRequest;
+      const request = validateGitHubContextRequest(message.payload);
       logger.debug('Processing GitHub request', { action: request.action });
 
       let result: GitHubContextResult | GitHubContextError;

packages/subagents/src/planner/__tests__/index.test.ts

@@ -162,8 +162,8 @@ describe('PlannerAgent', () => {
       const response = await planner.handleMessage(message);
 
       expect(response).toBeTruthy();
-      expect(response?.type).toBe('response');
-      expect((response?.payload as { error?: string }).error).toContain('Unknown action');
+      expect(response?.type).toBe('error');
+      expect((response?.payload as { error?: string }).error).toContain('Invalid planning request');
     });
 
     it('should generate correct response message structure', async () => {

packages/subagents/src/planner/index.ts

@@ -3,6 +3,7 @@
  * Analyzes GitHub issues and creates actionable development plans
  */
 
+import { validatePlanningRequest } from '../schemas/messages.js';
 import type { Agent, AgentContext, Message } from '../types';
 import type { Plan, PlanningError, PlanningRequest, PlanningResult } from './types';
 
@@ -33,7 +34,7 @@ export class PlannerAgent implements Agent {
     }
 
     try {
-      const request = message.payload as unknown as PlanningRequest;
+      const request = validatePlanningRequest(message.payload);
       logger.debug('Processing planning request', { action: request.action });
 
       let result: PlanningResult | PlanningError;

packages/subagents/src/schemas/__tests__/messages.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Subagent Message Schema Tests
+ * Validates inter-agent message payloads
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  ExplorationRequestSchema,
+  GitHubContextRequestSchema,
+  PlanningRequestSchema,
+  validateExplorationRequest,
+  validateGitHubContextRequest,
+  validatePlanningRequest,
+} from '../messages.js';
+
+describe('PlanningRequestSchema', () => {
+  it('should validate valid planning request', () => {
+    const input = {
+      action: 'plan',
+      issueNumber: 42,
+      useExplorer: true,
+      detailLevel: 'detailed',
+      strategy: 'sequential',
+    };
+
+    const result = PlanningRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.action).toBe('plan');
+      expect(result.data.issueNumber).toBe(42);
+      expect(result.data.useExplorer).toBe(true);
+    }
+  });
+
+  it('should allow optional fields', () => {
+    const input = {
+      action: 'plan',
+      issueNumber: 1,
+    };
+
+    const result = PlanningRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  it('should reject negative issue number', () => {
+    const input = {
+      action: 'plan',
+      issueNumber: -1,
+    };
+
+    const result = PlanningRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject invalid action', () => {
+    const input = {
+      action: 'invalid',
+      issueNumber: 1,
+    };
+
+    const result = PlanningRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject invalid detail level', () => {
+    const input = {
+      action: 'plan',
+      issueNumber: 1,
+      detailLevel: 'invalid',
+    };
+
+    const result = PlanningRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('ExplorationRequestSchema', () => {
+  it('should validate pattern exploration', () => {
+    const input = {
+      action: 'pattern' as const,
+      query: 'authentication',
+      threshold: 0.8,
+      limit: 10,
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success && result.data.action === 'pattern') {
+      expect(result.data.action).toBe('pattern');
+      expect(result.data.query).toBe('authentication');
+    }
+  });
+
+  it('should validate similar code search', () => {
+    const input = {
+      action: 'similar' as const,
+      filePath: 'src/auth/token.ts',
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  it('should validate relationships query', () => {
+    const input = {
+      action: 'relationships' as const,
+      component: 'MyClass',
+      type: 'all' as const,
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success && result.data.action === 'relationships') {
+      expect(result.data.type).toBe('all');
+    }
+  });
+
+  it('should reject empty query', () => {
+    const input = {
+      action: 'pattern' as const,
+      query: '',
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject invalid action', () => {
+    const input = {
+      action: 'invalid',
+      query: 'test',
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject threshold out of range', () => {
+    const input = {
+      action: 'pattern' as const,
+      query: 'test',
+      threshold: 1.5,
+    };
+
+    const result = ExplorationRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('GitHubContextRequestSchema', () => {
+  it('should validate context request for issue', () => {
+    const input = {
+      action: 'context' as const,
+      issueNumber: 42,
+    };
+
+    const result = GitHubContextRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.action).toBe('context');
+      expect(result.data.issueNumber).toBe(42);
+    }
+  });
+
+  it('should validate search with options', () => {
+    const input = {
+      action: 'search' as const,
+      query: 'authentication bug',
+      searchOptions: {
+        type: 'issue',
+        state: 'open',
+        labels: ['bug', 'high-priority'],
+      },
+    };
+
+    const result = GitHubContextRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.query).toBe('authentication bug');
+    }
+  });
+
+  it('should validate context request', () => {
+    const input = {
+      action: 'context' as const,
+      issueNumber: 42,
+      includeCodeContext: true,
+    };
+
+    const result = GitHubContextRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  it('should allow requests without optional fields', () => {
+    const input = {
+      action: 'index' as const,
+    };
+
+    const result = GitHubContextRequestSchema.safeParse(input);
+    expect(result.success).toBe(true);
+  });
+
+  it('should reject invalid action', () => {
+    const input = {
+      action: 'invalid-action',
+    };
+
+    const result = GitHubContextRequestSchema.safeParse(input);
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('Validation Functions', () => {
+  describe('validatePlanningRequest', () => {
+    it('should return validated data for valid input', () => {
+      const input = {
+        action: 'plan',
+        issueNumber: 42,
+      };
+
+      const result = validatePlanningRequest(input);
+      expect(result.action).toBe('plan');
+      expect(result.issueNumber).toBe(42);
+    });
+
+    it('should throw descriptive error for invalid input', () => {
+      const input = {
+        action: 'plan',
+        issueNumber: 'not-a-number',
+      };
+
+      expect(() => validatePlanningRequest(input)).toThrow('Invalid planning request');
+      expect(() => validatePlanningRequest(input)).toThrow('issueNumber');
+    });
+  });
+
+  describe('validateExplorationRequest', () => {
+    it('should return validated data for valid input', () => {
+      const input = {
+        action: 'pattern' as const,
+        query: 'auth',
+      };
+
+      const result = validateExplorationRequest(input);
+      expect(result.action).toBe('pattern');
+      if (result.action === 'pattern') {
+        expect(result.query).toBe('auth');
+      }
+    });
+
+    it('should throw descriptive error for invalid input', () => {
+      const input = {
+        action: 'pattern' as const,
+        query: '',
+      };
+
+      expect(() => validateExplorationRequest(input)).toThrow('Invalid exploration request');
+    });
+  });
+
+  describe('validateGitHubContextRequest', () => {
+    it('should return validated data for valid input', () => {
+      const input = {
+        action: 'context' as const,
+        issueNumber: 42,
+      };
+
+      const result = validateGitHubContextRequest(input);
+      expect(result.action).toBe('context');
+      expect(result.issueNumber).toBe(42);
+    });
+
+    it('should throw descriptive error for invalid input', () => {
+      const input = {
+        action: 'invalid',
+      };
+
+      expect(() => validateGitHubContextRequest(input)).toThrow('Invalid GitHub context request');
+    });
+  });
+});