fix: rename agent_spec.format → outputFormat + guard registration collisions (#1127) (#1144)

* fix: rename agent_spec.format → outputFormat + guard registration collisions (#1127)

The flat composite registration in buildRegistrationSchema used a silent
"first wins" merge across per-action fields. agent_spec.format (enum
full|prompt-only, default full) was registered before doctor.format and
init.format (enum table|json), so the SDK-level schema injected the wrong
default into every orchestrate call and rejected doctor/init's valid
format values at the MCP boundary. Parity tests missed it because they
dispatch() directly, bypassing the registered SDK schema.

Rename agent_spec.format → outputFormat to eliminate the current
collision. Add a narrow collision-detection guard that throws at
registration time when two actions declare the same field with
incompatible base types, different enum value sets, or different
defaults — catching the class of bug structurally. Constraint drift
(min/max/optionality) remains first-wins since handler-level schemas
re-validate.

New regression tests exercise the real exarchos_orchestrate registry
through the registration schema, confirming doctor({}),
doctor({format:'json'}), init({nonInteractive:true}), and
agent_spec({outputFormat:...}) are all reachable end-to-end.

Closes #1127.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(mcp): classify ZodLiteral/NativeEnum/Union as enum for collision detection

Addresses CodeRabbit feedback on PR #1144: the contract classifier
treated ZodLiteral, ZodNativeEnum, and ZodUnion as 'other', which
meant describeContractConflict couldn't spot mismatches between
two actions declaring the same field with incompatible literal
values, native-enum sets, or union-of-literals sets — exactly the
#1127-class hazard the registration-time guard is meant to catch.

Teach extractEnumValues to pull values from:
  * ZodLiteral (1-member enum; JSON-stringified for non-string values)
  * ZodNativeEnum (TS enum values, dedup-stringified)
  * ZodUnion whose branches are all ZodLiteral

Heterogeneous unions (e.g. z.union([z.string(), z.array(z.string())]))
still fall through to baseKind, preserving current behavior — only
the enum-ish cases get new scrutiny.

Also adds the regression tests CodeRabbit called out:
  * default-only collision ('full' vs 'json' on same base type)
  * literal-valued field with different values
  * union-of-literals with divergent value sets

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

documentation/reference/tools/orchestrate.md

@@ -360,15 +360,15 @@ Retrieve an agent specification for subagent dispatch. Returns the agent's syste
 {
   "action": "agent_spec",
   "agent": "implementer",
-  "format": "full"
+  "outputFormat": "full"
 }
 ```
 
 | Parameter | Required | Type | Description |
 |-----------|----------|------|-------------|
 | `agent` | yes | string (enum) | Agent identifier from the registered spec list |
 | `context` | no | object | Key-value pairs for template variable interpolation in prompts |
-| `format` | no | `"full"` \| `"prompt-only"` (default: `"full"`) | `full` returns the complete spec; `prompt-only` returns just the system prompt |
+| `outputFormat` | no | `"full"` \| `"prompt-only"` (default: `"full"`) | `full` returns the complete spec; `prompt-only` returns just the system prompt. Renamed from `format` in #1127 to avoid a registration collision with the `format: "table" \| "json"` parameter on `doctor` and `init`. |
 
 Phases: all. Role: `any`.
 

servers/exarchos-mcp/src/agents/handler.test.ts

@@ -6,7 +6,7 @@ import { handleAgentSpec, agentSpecSchema } from './handler.js';
 describe('handleAgentSpec', () => {
   it('AgentSpec_ValidAgent_ReturnsFullSpec', async () => {
     // Arrange
-    const args = { agent: 'implementer' as const, format: 'full' as const };
+    const args = { agent: 'implementer' as const, outputFormat: 'full' as const };
 
     // Act
     const result = await handleAgentSpec(args);
@@ -62,7 +62,7 @@ describe('handleAgentSpec', () => {
         requirements: 'Must validate email format',
         filePaths: 'src/login.ts, src/login.test.ts',
       },
-      format: 'full' as const,
+      outputFormat: 'full' as const,
     };
 
     // Act
@@ -87,7 +87,7 @@ describe('handleAgentSpec', () => {
       context: {
         taskDescription: 'Build it',
       },
-      format: 'full' as const,
+      outputFormat: 'full' as const,
     };
 
     // Act
@@ -112,7 +112,7 @@ describe('handleAgentSpec', () => {
         reviewScope: 'PR #42',
         designRequirements: 'DR-1: Must have tests',
       },
-      format: 'prompt-only' as const,
+      outputFormat: 'prompt-only' as const,
     };
 
     // Act
@@ -137,29 +137,29 @@ describe('handleAgentSpec', () => {
 });
 
 describe('agentSpecSchema', () => {
-  it('should accept valid full format', () => {
+  it('should accept valid full outputFormat', () => {
     const result = agentSpecSchema.safeParse({
       agent: 'implementer',
-      format: 'full',
+      outputFormat: 'full',
     });
     expect(result.success).toBe(true);
   });
 
-  it('should accept valid prompt-only format', () => {
+  it('should accept valid prompt-only outputFormat', () => {
     const result = agentSpecSchema.safeParse({
       agent: 'reviewer',
-      format: 'prompt-only',
+      outputFormat: 'prompt-only',
     });
     expect(result.success).toBe(true);
   });
 
-  it('should default format to full', () => {
+  it('should default outputFormat to full', () => {
     const result = agentSpecSchema.safeParse({
       agent: 'fixer',
     });
     expect(result.success).toBe(true);
     if (result.success) {
-      expect(result.data.format).toBe('full');
+      expect(result.data.outputFormat).toBe('full');
     }
   });
 

servers/exarchos-mcp/src/agents/handler.ts

@@ -16,7 +16,7 @@ const AGENT_IDS = ALL_AGENT_SPECS.map(s => s.id) as [string, ...string[]];
 export const agentSpecSchema = z.object({
   agent: z.enum(AGENT_IDS),
   context: z.record(z.string(), z.string()).optional(),
-  format: z.enum(['full', 'prompt-only']).default('full'),
+  outputFormat: z.enum(['full', 'prompt-only']).default('full'),
 });
 
 type AgentSpecArgs = z.infer<typeof agentSpecSchema>;
@@ -52,7 +52,7 @@ function interpolatePrompt(
 // ─── Handler ────────────────────────────────────────────────────────────────
 
 export async function handleAgentSpec(args: AgentSpecArgs): Promise<ToolResult> {
-  const { agent, context = {}, format = 'full' } = args;
+  const { agent, context = {}, outputFormat = 'full' } = args;
 
   // Find spec by agent ID
   const spec: AgentSpec | undefined = ALL_AGENT_SPECS.find(s => s.id === agent);
@@ -72,7 +72,7 @@ export async function handleAgentSpec(args: AgentSpecArgs): Promise<ToolResult>
   const { systemPrompt, unresolvedVars } = interpolatePrompt(spec.systemPrompt, context);
 
   // Format: prompt-only
-  if (format === 'prompt-only') {
+  if (outputFormat === 'prompt-only') {
     return {
       success: true,
       data: {

servers/exarchos-mcp/src/orchestrate/composite.test.ts

@@ -419,7 +419,7 @@ describe('handleOrchestrate', () => {
       const args = {
         action: 'agent_spec',
         agent: 'implementer',
-        format: 'full',
+        outputFormat: 'full',
       };
 
       // Act
@@ -428,7 +428,7 @@ describe('handleOrchestrate', () => {
       // Assert
       expect(result).toBe(expected);
       expect(handleAgentSpec).toHaveBeenCalledWith(
-        { agent: 'implementer', format: 'full' },
+        { agent: 'implementer', outputFormat: 'full' },
         STATE_DIR,
       );
     });

servers/exarchos-mcp/src/registry.test.ts

@@ -113,6 +113,188 @@ describe('buildRegistrationSchema', () => {
     const schema = buildRegistrationSchema(testActions);
     expect(schema).toBeInstanceOf(z.ZodObject);
   });
+
+  // ─── Collision-detection guard (regression for #1127) ─────────────────────
+
+  it('should throw when two actions declare the same field with incompatible enums', () => {
+    const colliding: readonly ToolAction[] = [
+      {
+        name: 'first',
+        description: 'First action',
+        schema: z.object({ format: z.enum(['full', 'prompt-only']).default('full') }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'second',
+        description: 'Second action',
+        schema: z.object({ format: z.enum(['table', 'json']).optional() }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/collides/);
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/first|second/);
+  });
+
+  it('should throw when two actions declare the same field with incompatible base types', () => {
+    const colliding: readonly ToolAction[] = [
+      {
+        name: 'a',
+        description: 'A',
+        schema: z.object({ limit: z.number().int() }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'b',
+        description: 'B',
+        schema: z.object({ limit: z.string() }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/collides/);
+  });
+
+  it('should throw when two actions share a field whose defaults differ', () => {
+    // Guards the "defaults diverge" arm of describeContractConflict: same
+    // base type (string), no enum, but mismatched defaults would otherwise
+    // let the first declaration silently shadow the second at the
+    // registration boundary.
+    const colliding: readonly ToolAction[] = [
+      {
+        name: 'first',
+        description: 'First action',
+        schema: z.object({ mode: z.string().default('full') }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'second',
+        description: 'Second action',
+        schema: z.object({ mode: z.string().default('json') }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/collides/);
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/Default values differ/);
+  });
+
+  it('should throw when two actions share a literal-valued field with different values', () => {
+    // Regression: before this fix, z.literal was classified as 'other' and
+    // defaults=none on both sides silently passed — two actions could bind
+    // the same field to incompatible literal values without detection.
+    const colliding: readonly ToolAction[] = [
+      {
+        name: 'first',
+        description: 'First',
+        schema: z.object({ tag: z.literal('alpha') }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'second',
+        description: 'Second',
+        schema: z.object({ tag: z.literal('beta') }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/collides/);
+  });
+
+  it('should throw when a union-of-literals field diverges across actions', () => {
+    // Union-of-literals is the hand-rolled form of z.enum(). Same contract
+    // semantics must apply: mismatched value sets must collide.
+    const colliding: readonly ToolAction[] = [
+      {
+        name: 'first',
+        description: 'First',
+        schema: z.object({
+          mode: z.union([z.literal('a'), z.literal('b')]),
+        }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'second',
+        description: 'Second',
+        schema: z.object({
+          mode: z.union([z.literal('a'), z.literal('c')]),
+        }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(colliding)).toThrow(/collides/);
+  });
+
+  it('should allow two actions to share a field when their schemas are structurally identical', () => {
+    const compatible: readonly ToolAction[] = [
+      {
+        name: 'create_pr',
+        description: 'Create',
+        schema: z.object({ prId: z.string().min(1) }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+      {
+        name: 'merge_pr',
+        description: 'Merge',
+        schema: z.object({ prId: z.string().min(1) }),
+        phases: new Set(['ideate']),
+        roles: new Set(['any']),
+      },
+    ];
+
+    expect(() => buildRegistrationSchema(compatible)).not.toThrow();
+  });
+
+  it('should not collide on format across the real orchestrate registry (#1127 regression)', () => {
+    const orchestrate = TOOL_REGISTRY.find((t) => t.name === 'exarchos_orchestrate')!;
+    expect(() => buildRegistrationSchema(orchestrate.actions)).not.toThrow();
+  });
+
+  it('should accept doctor format values against the real orchestrate registration schema', () => {
+    const orchestrate = TOOL_REGISTRY.find((t) => t.name === 'exarchos_orchestrate')!;
+    const schema = buildRegistrationSchema(orchestrate.actions);
+
+    // Regression for #1127: before the fix, agent_spec.format (full|prompt-only)
+    // shadowed doctor/init.format (table|json), making these payloads fail
+    // validation at the registered-tool boundary.
+    expect(schema.safeParse({ action: 'doctor' }).success).toBe(true);
+    expect(schema.safeParse({ action: 'doctor', format: 'json' }).success).toBe(true);
+    expect(schema.safeParse({ action: 'doctor', format: 'table' }).success).toBe(true);
+    expect(schema.safeParse({ action: 'init', nonInteractive: true }).success).toBe(true);
+    expect(schema.safeParse({ action: 'init', format: 'json' }).success).toBe(true);
+  });
+
+  it('should expose agent_spec outputFormat on the real orchestrate registration schema', () => {
+    const orchestrate = TOOL_REGISTRY.find((t) => t.name === 'exarchos_orchestrate')!;
+    const schema = buildRegistrationSchema(orchestrate.actions);
+
+    expect(
+      schema.safeParse({
+        action: 'agent_spec',
+        agent: 'implementer',
+        outputFormat: 'full',
+      }).success,
+    ).toBe(true);
+    expect(
+      schema.safeParse({
+        action: 'agent_spec',
+        agent: 'implementer',
+        outputFormat: 'prompt-only',
+      }).success,
+    ).toBe(true);
+  });
 });
 
 // ─── Type Coercion Tests ─────────────────────────────────────────────────────