ADR-0020: Agent orchestration in the core, providers and tools outside
- Status: Accepted
- Date: 2026-06-24
- Deciders: jka
- Decision: D20
Context
Should the agent be an extension? VS Code places agent orchestration in extensions. rio's agent reads files, proposes writes and later runs commands, so where the tool-executing loop lives decides where the security boundary is.
Decision
The agent is split along a line of security and volatility.
- In the core (durable, security-critical): the orchestration loop (conversation state, tool dispatch), the review of proposed changes, and the guardrails around tool execution. Every tool call goes through one permission model, and the user reviews proposals the same way whichever provider is in use.
- Outside the core (volatile): concrete providers (ADR-0008) and additional tools beyond the built-in ones.
The provider interface and the tool interface are candidates for alignment with the Model Context Protocol (MCP) rather than a bespoke contract.
Alternatives considered
Orchestration in an extension, as in VS Code. Rejected because the security boundary and cross-provider consistency would then depend on extension code.
Consequences
- Tool specifications and the system prompt are composed in the core and handed to every provider (ADR-0034, ADR-0101), so a provider cannot opt out of a restriction such as plan mode.
- Provider extensions contain no tool list and no approval logic.
- MCP alignment is still open.