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