Skip to content

Commit 5f73ea6

Browse files
authored
feat: add provider admission policy (#6) (#19)
1 parent c2d85e4 commit 5f73ea6

9 files changed

Lines changed: 437 additions & 3 deletions

File tree

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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`

‎packages/guardrails/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Current contents focus on the first thin-distribution slice:
4747
- packaged custom config dir profile
4848
- packaged plugin for runtime guardrail hooks
4949
- guarded `implement` and `review` agents plus packaged `/implement`, `/review`, `/ship`, and `/handoff` workflow commands
50+
- declarative provider admission policy for `zai`, `openai`, and the isolated OpenRouter evaluation lane
5051
- scenario coverage for managed config precedence, project-local asset compatibility, plugin behavior, and workflow safety defaults
5152

5253
Planned next slices are tracked in the fork:
@@ -72,6 +73,8 @@ It respects an existing `OPENCODE_CONFIG_DIR` so project- or environment-specifi
7273

7374
The packaged profile defaults to the `implement` agent. Review and release-readiness work should run through the packaged `/review`, `/ship`, and `/handoff` commands so the workflow stays read-only at the gate layer.
7475

76+
Provider admission is also packaged here. Standard confidential-code work is admitted on the `zai` and `openai` lane. OpenRouter-backed candidates are available only through the dedicated `provider-eval` lane so evaluation traffic does not silently become the default implementation path.
77+
7578
## Managed deployment
7679

7780
Copy [managed/opencode.json](/Users/teradakousuke/Developer/opencode/packages/guardrails/managed/opencode.json) into the system managed config directory:

‎packages/guardrails/managed/opencode.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,40 @@
11
{
22
"$schema": "https://opencode.ai/config.json",
3+
"enabled_providers": [
4+
"zai",
5+
"openai",
6+
"openrouter"
7+
],
38
"share": "disabled",
49
"server": {
510
"hostname": "127.0.0.1",
611
"mdns": false
712
},
13+
"provider": {
14+
"zai": {
15+
"whitelist": [
16+
"glm-5",
17+
"glm-4.5",
18+
"glm-4.5-air"
19+
]
20+
},
21+
"openai": {
22+
"whitelist": [
23+
"gpt-5",
24+
"gpt-5-mini",
25+
"gpt-5-nano",
26+
"gpt-4.1"
27+
]
28+
},
29+
"openrouter": {
30+
"whitelist": [
31+
"openai/gpt-5",
32+
"openai/gpt-5-mini",
33+
"anthropic/claude-sonnet-4.5",
34+
"google/gemini-2.5-pro"
35+
]
36+
}
37+
},
838
"permission": {
939
"edit": "ask",
1040
"task": "ask",

‎packages/guardrails/profile/AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@
1010
- Treat `.opencode/guardrails/` as plugin-owned runtime state, not a manual editing surface.
1111
- Use `implement` as the guarded default primary agent. Route review, ship, and handoff work through the packaged `/review`, `/ship`, and `/handoff` commands instead of freeform release flows.
1212
- Keep review paths read-only. If a workflow needs edits, return to `implement` or a project-local implementation agent instead of widening the review agent.
13+
- Keep provider admission explicit. Standard confidential-code work stays on the admitted `zai` and `openai` lane; OpenRouter-backed evaluation belongs on `provider-eval` or `/provider-eval` only.
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
description: Evaluate admitted OpenRouter-backed candidates without widening the default confidential-code lane.
3+
mode: subagent
4+
model: openrouter/openai/gpt-5-mini
5+
permission:
6+
"*": deny
7+
read: allow
8+
grep: allow
9+
glob: allow
10+
list: allow
11+
lsp: allow
12+
skill: allow
13+
webfetch: ask
14+
bash:
15+
"*": deny
16+
"git diff *": allow
17+
"git status *": allow
18+
"git show *": allow
19+
"git log *": allow
20+
---
21+
22+
Use this lane only for provider admission work.
23+
24+
Keep the output evidence-based:
25+
26+
- cite the admitted model and provider choice explicitly
27+
- call out routing or data-policy assumptions that still need confirmation
28+
- do not widen the default implementation lane from this agent
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
description: Evaluate admitted provider candidates in the isolated provider-eval lane.
3+
agent: provider-eval
4+
subtask: true
5+
---
6+
7+
Evaluate the requested provider or model candidate using the dedicated provider-eval lane.
8+
9+
Required sections:
10+
11+
- Candidate
12+
- Evidence
13+
- Routing and data-policy notes
14+
- Recommendation
15+
- Follow-up config change
16+
17+
Default scope is provider admission and confidential-code suitability, not general implementation work.

‎packages/guardrails/profile/opencode.json‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,41 @@
11
{
22
"$schema": "https://opencode.ai/config.json",
33
"default_agent": "implement",
4+
"enabled_providers": [
5+
"zai",
6+
"openai",
7+
"openrouter"
8+
],
49
"share": "disabled",
510
"server": {
611
"hostname": "127.0.0.1",
712
"mdns": false
813
},
9-
"plugin": [
10-
"./plugins/guardrail.ts"
11-
],
14+
"provider": {
15+
"zai": {
16+
"whitelist": [
17+
"glm-5",
18+
"glm-4.5",
19+
"glm-4.5-air"
20+
]
21+
},
22+
"openai": {
23+
"whitelist": [
24+
"gpt-5",
25+
"gpt-5-mini",
26+
"gpt-5-nano",
27+
"gpt-4.1"
28+
]
29+
},
30+
"openrouter": {
31+
"whitelist": [
32+
"openai/gpt-5",
33+
"openai/gpt-5-mini",
34+
"anthropic/claude-sonnet-4.5",
35+
"google/gemini-2.5-pro"
36+
]
37+
}
38+
},
1239
"permission": {
1340
"edit": "ask",
1441
"task": "ask",

0 commit comments

Comments
 (0)