Epic: Per-Agent Options (Model, MCP/Skills, Variant) – AgentOptions

[maddes8cht]

Description

Currently, every opencode run invocation starts without additional flags – model, MCP servers, or skills are not controlled. A workflow should be able to specify per-agent:

• Model (--model / -m): e.g. anthropic/claude-sonnet-4 for the author, openai/gpt-4o for the auditor
• MCP servers / Skills (--pure or targeted selection): e.g. --pure for a simple code generator, or specific MCP servers for a research agent
• Other opencode options like --variant (reasoning effort)

This configuration must be settable via GUI, CLI, and workflow JSON.

Prerequisite

This issue builds on #23. Issue #23 provides the base infrastructure:

• OpenCodeOptions dataclass with to_cli_args()
• OpenCodeRunner.run() accepts OpenCodeOptions
• Global defaults in Config and WorkflowConfig

#23 must be completed before this issue can be implemented.

Design

1. Data Model: AgentOptions

Extends OpenCodeOptions from #23 with per-agent-specific fields:

@dataclass
class AgentOptions(OpenCodeOptions):
    # Inherits: model, agent, variant, pure, log_level, extra_args
    pass  # initially identical – extensions possible later

Alternative: agent_options: dict[str, OpenCodeOptions] in WorkflowConfig (simpler, no new dataclass needed).

2. Storage Locations (Override Order)

CLI --agent-options  >  Workflow JSON (agent_options.{name})  >  Agent Frontmatter  >  Workflow Defaults (#23)  >  Config Defaults (#23)

(a) Agent Frontmatter (default per agent):

---
name: amala
role: author
model: anthropic/claude-sonnet-4
pure: true
---

(b) Workflow JSON (override per agent):

{
  "loop_agents": ["amala", "vera"],
  "agent_options": {
    "amala": { "model": "anthropic/claude-sonnet-4", "pure": true },
    "vera":  { "model": "openai/gpt-4o", "variant": "high" }
  }
}

(c) CLI (global override for all agents):

python openloop.py --cli --workflow wf.json --agent-options "model=openai/gpt-4o"

3. Runner Extension

OpenCodeRunner.run() gets a parameter agent_opts: Optional[OpenCodeOptions] = None – builds additional CLI flags (merged with global defaults from #23).

4. GUI Extension

Per agent in the slot an Options button (gear icon) that opens a dialog:

Agent Options: amala
+----------------------------------+
| Model:  anthropic/claude-sonnet-4 |
| Variant: [high | max | minimal]   |
| X Pure mode (no plugins)         |
| Extra Args: [______________]      |
+----------------------------------+

Sub-Issues (ToDo)

• Configuration System (core/config.py) #1 Optional Frontmatter Fields – AgentLoader reads model/agent/variant/pure/extra_args from YAML frontmatter
• Core State Management (core/state.py, core/parser.py) #2 WorkflowConfig – agent_options: dict[str, OpenCodeOptions] in WorkflowConfig, serialization in from_dict()/to_dict()
• Agent Definition Loader (core/agent.py) #3 Engine Merging – _execute_agent() merges: Config Defaults (Global OpenCode Defaults (opencode_defaults) for Model, Agent, Variant, Pure, etc. #23) > Workflow Defaults (Global OpenCode Defaults (opencode_defaults) for Model, Agent, Variant, Pure, etc. #23) > Agent Frontmatter > Workflow agent_options > CLI Overrides
• Subprocess Runner (core/runner.py) #4 CLI – New --agent-options flag
• Execution Engine (core/engine.py) #5 GUI – Options button and dialog per slot entry
• Main Entry Point (openloop.py) #6 Integration Tests

Scope

• This feature allows per-agent overrides based on the global defaults from Global OpenCode Defaults (opencode_defaults) for Model, Agent, Variant, Pure, etc. #23.
• The complete merge order: Config (#23) > Workflow (#23) > Agent Frontmatter > Workflow agent_options > CLI > Runner
• Complements Epic: Parallel Execution of Agents in the Loop Phase (Parallel Groups) #21 (Parallel Groups): each parallel agent can use its own model.
• Independent of Epic: Sub-Workflow Support in Preparation/Loop/Finalization Slots #18 (Sub-Workflows) and Epic: Scripts as third element category in slots (Pre/Post-Hooks) #19 (Script Hooks).