|
| 1 | +# ADR 002: Provider Admission Lanes |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +Accepted |
| 6 | + |
| 7 | +## Context |
| 8 | + |
| 9 | +The internal product needs a stable answer for confidential-code routing before it can honestly be called an MVP. |
| 10 | + |
| 11 | +OpenCode already exposes the needed primitives in config, provider metadata, commands, agents, and plugins. The missing piece is not another fork-level provider abstraction. It is a thin-distribution policy that: |
| 12 | + |
| 13 | +- admits a small provider set intentionally |
| 14 | +- keeps standard work separate from evaluation traffic |
| 15 | +- blocks free, preview, or otherwise non-approved models for confidential repositories |
| 16 | +- stays declarative in config and verifiable at runtime |
| 17 | + |
| 18 | +This follows the same philosophy imported from `claude-code-skills` epic `#130` and the harness-engineering references: |
| 19 | + |
| 20 | +- mechanism before prose |
| 21 | +- fastest reliable layer first |
| 22 | +- pointer-based instructions |
| 23 | +- runtime proof instead of "the code exists" |
| 24 | + |
| 25 | +## Decision |
| 26 | + |
| 27 | +Adopt three admission lanes: |
| 28 | + |
| 29 | +1. `zai` and `openai` are the standard confidential-code lane. |
| 30 | +2. `openrouter` is admitted only as a separate evaluation lane. |
| 31 | +3. OpenRouter-backed evaluation stays on an explicit `provider-eval` agent and command instead of widening the default implementation lane. |
| 32 | + |
| 33 | +The policy is implemented in two layers: |
| 34 | + |
| 35 | +- config expresses admitted providers and model allowlists |
| 36 | +- the guardrail plugin enforces lane usage at runtime through `chat.params` |
| 37 | + |
| 38 | +## Policy |
| 39 | + |
| 40 | +### Standard lane |
| 41 | + |
| 42 | +- admitted providers: `zai`, `openai` |
| 43 | +- admitted models are pinned through provider allowlists |
| 44 | +- preview, free, and non-approved variants are excluded by default |
| 45 | + |
| 46 | +### Evaluation lane |
| 47 | + |
| 48 | +- admitted provider: `openrouter` |
| 49 | +- admitted models are a narrow allowlist of approved evaluation candidates |
| 50 | +- the lane is entered only through the packaged `provider-eval` workflow |
| 51 | + |
| 52 | +### Confidential-repo rule |
| 53 | + |
| 54 | +For confidential repositories: |
| 55 | + |
| 56 | +- do not use free models |
| 57 | +- do not use preview, alpha, beta, or experimental models |
| 58 | +- do not use OpenRouter outside the explicit evaluation lane |
| 59 | +- do not expand the admitted model set without a docs-backed review of routing and data controls |
| 60 | + |
| 61 | +## Rationale |
| 62 | + |
| 63 | +This keeps the runtime upstream-compatible while still answering the real policy question: |
| 64 | + |
| 65 | +- standard work has a stable provider set |
| 66 | +- evaluation traffic is explicit instead of accidental |
| 67 | +- adding a new OpenRouter candidate requires a deliberate config change |
| 68 | +- plugin enforcement means project-local config cannot silently widen the lane |
| 69 | + |
| 70 | +## Consequences |
| 71 | + |
| 72 | +### Positive |
| 73 | + |
| 74 | +- provider policy is declarative and testable |
| 75 | +- the default lane is smaller and easier to reason about |
| 76 | +- evaluation traffic is visible in workflow and logs |
| 77 | +- future provider additions become explicit admission decisions, not casual model switches |
| 78 | + |
| 79 | +### Negative |
| 80 | + |
| 81 | +- the policy duplicates some intent across config and plugin checks |
| 82 | +- OpenRouter evaluation remains intentionally narrower than raw upstream capability |
| 83 | +- new model admissions require docs and allowlist maintenance |
| 84 | + |
| 85 | +## Verification |
| 86 | + |
| 87 | +Issue `#6` must prove: |
| 88 | + |
| 89 | +- admitted providers and model allowlists load from config |
| 90 | +- OpenRouter-backed models are available only in the explicit evaluation lane |
| 91 | +- blocked provider misuse throws at runtime through the guardrail plugin |
| 92 | + |
| 93 | +## Sources |
| 94 | + |
| 95 | +- `claude-code-skills` epic `#130` |
| 96 | +- `claude-code-skills` README |
| 97 | +- `claude-code-skills/docs/references/harness-engineering-best-practices-2026.md` |
| 98 | +- Anthropic `The Complete Guide to Building Skills for Claude` |
| 99 | +- OpenCode config docs: `https://opencode.ai/docs/config` |
| 100 | +- OpenRouter provider routing docs: `https://openrouter.ai/docs/guides/routing/provider-selection` |
| 101 | +- OpenAI pricing: `https://openai.com/api/pricing/` |
| 102 | +- OpenAI data controls: `https://developers.openai.com/api/docs/guides/your-data` |
| 103 | +- Z.AI pricing: `https://docs.z.ai/guides/overview/pricing` |
| 104 | +- Z.AI OpenCode guide: `https://docs.z.ai/devpack/tool/opencode` |
0 commit comments