How Claude and Codex Models Are Configured for Validation in Archon Workflows

Archon validates Claude and Codex model configurations through a three-tiered system: utility helpers in model-validation.ts, Zod schema enforcement in dag-node.ts, and workflow-level checks in loader.ts that prevent incompatible provider-model pairs from executing.

Archon is an open-source workflow orchestration engine that strictly enforces AI model compatibility at both parse time and load time. When defining Claude and Codex models for validation within Archon workflows, developers must adhere to specific naming patterns that the framework verifies through TypeScript utilities and schema validators. This architecture ensures that Claude-specific models (like sonnet or opus) cannot be mistakenly assigned to Codex providers, and vice versa, before the workflow ever reaches the execution engine.

Model Validation Architecture

Archon implements provider-model compatibility checks at three distinct layers to catch configuration errors early. The validation chain runs during workflow file parsing, DAG node instantiation, and final workflow assembly.

Utility Helpers in model-validation.ts

The core logic resides in packages/workflows/src/model-validation.ts. The isClaudeModel function defines valid Claude model patterns, while isModelCompatible performs the cross-reference check.

export function isClaudeModel(model: string): boolean {
  return (
    model === 'sonnet' ||
    model === 'opus' ||
    model === 'haiku' ||
    model === 'inherit' ||
    model.startsWith('claude-')
  );
}

export function isModelCompatible(provider: 'claude' | 'codex', model?: string): boolean {
  if (!model) return true;
  return provider === 'claude' ? isClaudeModel(model) : !isClaudeModel(model);
}

The isClaudeModel predicate accepts four specific aliases (sonnet, opus, haiku, inherit) plus any string prefixed with claude-. For the Codex provider, valid models are explicitly defined as anything that does not match the Claude pattern.

Schema Validation in dag-node.ts

When parsing individual workflow nodes, the Zod schema in packages/workflows/src/schemas/dag-node.ts (lines 89-96) invokes isModelCompatible to validate the provider and model fields. If the combination is invalid, the parser injects a custom Zod issue that halts workflow construction.

if (!hasBash && !hasLoop && !hasScript && data.provider && data.model) {
  if (!isModelCompatible(data.provider, data.model)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `model "${data.model}" is not compatible with provider "${data.provider}"`,
    });
  }
}

This check runs for all AI-powered node types (e.g., prompt, command, script) that specify both a provider and a model.

Workflow-Level Validation in loader.ts

The final safety gate occurs in packages/workflows/src/loader.ts (lines 73-88). During workflow loading, Archon extracts top-level provider and model declarations and runs the same compatibility check. An invalid combination at this stage aborts loading with a descriptive error before the workflow object is fully instantiated.

Provider-Specific Validation Rules

Archon strictly partitions model namespaces between providers to prevent SDK mismatches.

Claude Provider:

• Accepts sonnet, opus, haiku, or inherit
• Accepts any model string beginning with claude-
• Rejects all non-Claude patterns

Codex Provider:

• Rejects all Claude-specific patterns listed above
• Accepts any other model identifier

This binary classification ensures that the workflow engine instantiates the correct underlying SDK client (Anthropic for Claude, OpenAI Codex for Codex) based on the validated model name.

Practical Configuration Examples

Valid Claude Node Configuration

nodes:
  - id: plan
    provider: claude
    model: opus   # ✅ matches Claude pattern

    prompt: |
      Draft a plan for the requested feature.

Invalid Codex Node (Validation Error)

nodes:
  - id: analyse
    provider: codex
    model: sonnet   # ❌ Claude model used with Codex

    prompt: |
      Explain the TypeScript type errors.

This configuration triggers the validation error: model "sonnet" is not compatible with provider "codex".

Programmatic Validation

You can invoke the validation logic directly in TypeScript:

import { isModelCompatible } from '@archon/workflows/src/model-validation';

const ok = isModelCompatible('claude', 'sonnet');  // returns true
const bad = isModelCompatible('codex', 'sonnet');  // returns false

Summary

• Validation occurs at three layers: utility functions (model-validation.ts), DAG node schemas (dag-node.ts), and workflow loading (loader.ts).
• Claude models include sonnet, opus, haiku, inherit, and any claude-* prefixed string.
• Codex models comprise all identifiers that do not match the Claude pattern.
• Invalid combinations (e.g., provider: codex with model: opus) produce immediate validation errors with explicit messages, preventing runtime SDK mismatches.

Frequently Asked Questions

What model names are valid for the Claude provider in Archon?

The Claude provider accepts four literal aliases—sonnet, opus, haiku, and inherit—plus any model string beginning with the prefix claude-. All other identifiers fail validation when paired with the claude provider.

Can I use a Claude model with the Codex provider?

No. Archon explicitly rejects Claude-style model names (including sonnet, opus, haiku, inherit, and claude-* patterns) when the provider is set to codex. The isModelCompatible function returns false for any such combination, triggering a schema validation error.

Where does Archon check provider-model compatibility?

Archon performs compatibility checks in three locations: the isModelCompatible helper in packages/workflows/src/model-validation.ts, the Zod schema refinement in packages/workflows/src/schemas/dag-node.ts (lines 89-96), and the workflow loader in packages/workflows/src/loader.ts (lines 73-88).

What happens if I specify an incompatible model in my workflow YAML?

Archon aborts the workflow loading process and emits a clear error message such as model "sonnet" is not compatible with provider "codex". This occurs during the parsing phase, preventing the workflow from reaching execution with an invalid SDK configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}