Skip to content

Commit 94433c0

Browse files
terisukeclaude
andcommitted
docs(adr): add ADR-007 multi-model delegation gates
Documents the design rationale for OpenCode's provider-aware task routing, mapping Claude Code's 7 Codex delegation gates to OpenCode's multi-provider equivalents. Refs #124 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
1 parent f052aa0 commit 94433c0

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# ADR 007: Multi-Model Delegation Gates
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Context
8+
9+
Claude Code routes all tasks to a single provider (Anthropic) via Codex delegation gates (7 hooks). OpenCode supports multiple providers (ZAI, OpenAI, Anthropic via OpenRouter, Google, etc.) and can assign different models per agent via `agent.model`.
10+
11+
This multi-model capability is OpenCode's primary competitive advantage. However, without guardrails, agents may be assigned suboptimal models (expensive models for trivial tasks, weak models for complex tasks), parallel execution may exceed rate limits, and costs may spiral without visibility.
12+
13+
## Decision
14+
15+
Add five delegation gates to `guardrail.ts` that leverage OpenCode's multi-provider architecture:
16+
17+
### 1. agent-model-mapping (chat.params)
18+
Advisory that logs when an agent is running on a model tier that doesn't match its expected workload. Three tiers: high (implement, security, architect), standard (review, tdd, build-error), low (explore, doc-updater, investigate).
19+
20+
### 2. delegation-budget-gate (tool.execute.before for task)
21+
Hard block that limits concurrent parallel tasks to `maxParallelTasks` (default 5). Tracks `active_task_count` in state.json, incremented on task start and decremented on task completion.
22+
23+
### 3. cost-tracking (chat.params + tool.execute.after)
24+
Accumulates `session_cost` from model cost metadata. Logs a warning event when session cost exceeds `maxSessionCost` threshold.
25+
26+
### 4. parallel-execution-gate (tool.execute.before for task)
27+
Integrated with delegation-budget-gate. Prevents unbounded parallel execution that could hit provider rate limits.
28+
29+
### 5. verify-agent-output (tool.execute.after for task)
30+
Advisory that detects trivially short agent output (< 20 characters), indicating the agent may have failed silently.
31+
32+
## Mapping to Claude Code Codex Gates
33+
34+
| Claude Code | OpenCode | Evolution |
35+
|---|---|---|
36+
| codex-task-gate | delegation-budget-gate | Single Codex → any provider |
37+
| codex-model-gate | agent-model-mapping | Fixed model → per-agent tier |
38+
| codex-parallel-gate | parallel-execution-gate | Same + per-provider limits |
39+
| codex-cost-gate | cost-tracking | Codex API → all providers |
40+
| codex-output-gate | verify-agent-output | Equivalent |
41+
42+
## Consequences
43+
44+
### Positive
45+
46+
- OpenCode gains structured cost visibility across all providers
47+
- Unbounded parallel execution is prevented
48+
- Model-agent mismatch is logged for optimization
49+
- The pattern extends naturally to per-provider rate limits in future
50+
51+
### Negative
52+
53+
- `active_task_count` tracking may drift if a task crashes without completing the after hook; periodic reconciliation may be needed
54+
- Tier assignments are static; dynamic assignment based on task complexity would be more accurate but requires deeper integration
55+
56+
## Sources
57+
58+
- `packages/opencode/src/tool/task.ts` — task delegation with agent model override
59+
- `packages/opencode/src/agent/agent.ts` — agent model field and config merge
60+
- `@opencode-ai/plugin` — Hooks interface (chat.params, tool.execute.before/after)
61+
- Claude Code Codex delegation gates (7 hooks) — reference implementation

0 commit comments

Comments
 (0)