---
title: Providers
description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemini, and Codex adapters.'
---

# Providers

## Provider Quick Browse

=== "Claude"

    - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
    - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
    - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
    - Managed phase implementers and optional nested workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Agent `model`

=== "Cursor"

    - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
    - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
    - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the exact `providers.cursor.dispatchArgs.model` value selected from the candidate ladder. OAT passes it byte-for-byte as the actual Task-level `model`; a `model` frontmatter value is only a default/fallback mechanism.
    - Cursor model strings are opaque. OAT does not infer family, effort, cost, or capability from their spelling; the configured candidate position owns the named tier meaning.
    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch. Each adopt/doctor command probes each distinct exact candidate once and shares one lazy broad-catalog lookup across that pass; the cache ends with the command.
    - A correlated accepted Task carrying the exact model argument plus the child sentinel proves argument eligibility for that account/client. It does not prove backend runtime identity; that remains `not-reported` without trusted Cursor telemetry or support confirmation. Structured rejection can establish `unknown-value`, while parent prose and broad `cursor-agent models` catalog presence remain diagnostic-only.
    - The [dated GPT-5.6 verification artifact](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md) preserves the original probe and a stream-JSON control pass. The controls observed no Task events, so the stop rule ran zero recommendation or exploratory candidates and retained the recommendation unchanged.
    - The artifact's structured second-pass block contains only allowlisted event fields, derived outcomes, sanitized auth presence, and identifier hashes. Exact request/session/tool-call IDs and credential-redacted unprojected streams from that pass remain in gitignored local project storage for support escalation.
    - The same public artifact retains the sanitized historical v1 text-mode record for provenance. That older section includes command arguments and prompts, stdout and stderr, exit and duration data, and capture-environment details such as user-specific binary paths; it is not limited to the structured second-pass allowlist.
    - Rule files render as `.cursor/rules/*.mdc`

=== "Copilot"

    - Project: `.agents/skills` -> `.github/skills`, `.agents/agents` -> `.github/agents`, `.agents/rules` -> `.github/instructions`
    - User: `~/.agents/skills` -> `~/.copilot/skills`, `~/.agents/agents` -> `~/.copilot/agents`
    - Rule files render as `.github/instructions/*.instructions.md`
    - Canonical always-on rules render with `applyTo: "**"` so Copilot activates them repo-wide; provider rules with exactly `applyTo: "**"` adopt back to `activation: always`
    - Comma-containing globs are not supported for Copilot rule sync because Copilot uses a comma-separated `applyTo` field

=== "Gemini"

    - Project: native-read canonical mappings (`.agents/skills` and `.agents/agents`)
    - User: native-read canonical mappings (`~/.agents/skills` and `~/.agents/agents`)
    - Gemini provider sync does not mirror to a provider-specific directory because canonical paths are read directly

=== "Codex"

    - Skills are native-read from `.agents/skills` (no mirrored sync action for skill mappings)
    - Agents are native-read from `.agents/agents` for canonical source-of-truth workflows
    - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
      - `.codex/agents/<role>.toml`
      - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
    - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
    - Project sync writes and maintains the version-controlled supported catalogue: Luna and Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and `max`, for both `oat-phase-implementer` and `oat-reviewer` (26 pinned variants). Sync writes files; it does not create a Git commit.
    - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
    - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
    - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
    - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
    - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
    - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions, and does not require provider restart/hot reload
    - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
    - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
    - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.
    - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
    - Missing depth and explicit depth `1` are sufficient for default phase execution. Invalid values or values below `1` block managed implementation preflight. `oat doctor` explains when depth `2` optional nesting is available.
    - The phase implementer directly executes its planned tasks from one Phase Scope, preserves one bounded commit per task, and returns phase-wide verification. It does not dispatch the phase reviewer.

## 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:

```bash
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` view. User-config candidates materialize under `~/.codex`.
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 a fresh
pinned-child fallback. An accepted child, including one that later returns
`BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
Claude and Cursor bind the exact model arguments described above. 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 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

## Adoption model

- Stray adoption is available in `oat init` and `oat status`.
- Adoption reconciles canonical plus the adopted provider first.
- 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`.

## Reference artifacts

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