Providers

Provider Quick Browse

Managed dispatch views

Reusable ordered candidate ladders live in workflow.dispatchCeiling.providers. The project or phase named ceiling is only a maximum over those candidates; it does not select one permanent model family for the project.

Adopt the complete ladder into an explicit owning config scope before sync:

oat config adopt dispatch-matrix --shared
oat config adopt dispatch-matrix --local
oat config adopt dispatch-matrix --user

Project-config candidates materialize into the tracked, version-controlled project .codex and .cursor views. User-config candidates materialize under ~/.codex and ~/.cursor. OAT does not auto-ignore project output or create its Git commit; the team owns that repository change.

At implementation time, the root passes the recorded named maximum through invocation-only --ceiling-tier, resolves one exact candidate per phase, and dispatches one phase implementer. Codex first attempts the resolver-returned materialized role as the native agent_type. The launcher records the target, model axis, and effort axis from that resolved payload; child self-report is not provenance and cannot replace those values. Only an explicit pre-start native role-selection rejection permits another target-preserving route. An accepted child, including one that later returns BLOCKED or lacks telemetry, is a task outcome rather than a fallback signal. Claude binds the exact model argument described above. Cursor launches the exact native variant. A missing or unselectable managed target blocks rather than falling back to the root target or a base role.

Scope rules

• Project scope: skills + agents + rules
• User scope: skills, plus the two bundled managed Codex and Cursor role definitions used only for user-owned target expansion (provider mappings vary by adapter)
• Rules are project-scoped only in this release
• Codex user-scope sync materializes user-config custom roles under ~/.codex; project-config and supported-catalogue output remains project-scoped and version controlled
• Cursor user-scope sync materializes user-config variants under ~/.cursor/agents; project-config and supported-catalogue output remains project-scoped and version controlled

Adoption model

• Stray adoption is available in oat init and oat status.
• Adoption reconciles canonical plus the adopted provider first.
• Native-read Cursor skill adoption moves the provider-local skill into .agents/skills without recreating a .cursor/skills view or manifest entry.
• Choosing Keep Cursor-only leaves the skill in place and records its exact normalized path in the project or user sync config.
• Rule adoption normalizes provider filenames back to canonical .agents/rules/*.md entries before cross-provider fanout.
• Cross-provider fanout is explicit via oat sync --scope all.

Provider mutation safety

The generic sync engine validates provider destinations for every operation that creates or updates a symlink, creates or updates a copy, or removes a managed provider path. The same guard applies across provider adapters; it is not Claude-specific.

Validation runs at three boundaries:

1. During planning, before a provider operation is classified.
2. Across the complete mutating plan before apply starts, so an already-unsafe later entry cannot allow earlier provider or manifest mutations.
3. Immediately before each entry's first filesystem mutation, so ancestry that changes after preflight fails closed.

A mutation is refused when its destination escapes the sync scope, equals the scope root, or has any existing parent that is a symbolic link or not a directory. The final managed destination is excluded from the ancestry walk, so an existing managed symlink can still be updated or removed normally.

Whole-plan preflight refusal leaves provider paths, canonical content, external symlink targets, and manifest state unchanged. If ancestry changes after preflight, the affected entry fails before its first removal or write and does not gain manifest ownership. OAT does not traverse, unlink, or rewrite the unsafe parent.

Reference artifacts

• .oat/projects/<scope>/<project>/spec.md (FR5)
• packages/cli/src/providers/**
• packages/cli/src/providers/shared/adapter.utils.ts