task: review and document agent selection

src/cli/cli-program.ts

@@ -94,9 +94,10 @@ Examples:
 
 Agent resolution order:
   1) --agent flag
-  2) OPENCODE_DEFAULT_AGENT
-  3) oh-my-opencode.json "default_run_agent"
-  4) Sisyphus (fallback)
+  2) OPENCODE_AGENT
+  3) OPENCODE_DEFAULT_AGENT
+  4) oh-my-opencode.json "default_run_agent"
+  5) Sisyphus (fallback)
 
 Available core agents:
   Sisyphus, Hephaestus, Prometheus, Atlas

src/cli/run/agent-resolver.ts

@@ -5,6 +5,7 @@ import { getAgentConfigKey, getAgentDisplayName } from "../../shared/agent-displ
 
 const CORE_AGENT_ORDER = ["sisyphus", "hephaestus", "prometheus", "atlas"] as const
 const DEFAULT_AGENT = "sisyphus"
+const ENV_AGENT_KEYS = ["OPENCODE_AGENT", "OPENCODE_DEFAULT_AGENT"] as const
 
 type EnvVars = Record<string, string | undefined>
 type CoreAgentKey = (typeof CORE_AGENT_ORDER)[number]
@@ -54,7 +55,9 @@ export const resolveRunAgent = (
   env: EnvVars = process.env
 ): string => {
   const cliAgent = normalizeAgentName(options.agent)
-  const envAgent = normalizeAgentName(env.OPENCODE_DEFAULT_AGENT)
+  const envAgent = ENV_AGENT_KEYS
+    .map((key) => normalizeAgentName(env[key]))
+    .find((agent) => agent !== undefined)
   const configAgent = normalizeAgentName(pluginConfig.default_run_agent)
   const resolved =
     cliAgent ??

src/cli/run/runner.test.ts

@@ -37,6 +37,38 @@ describe("resolveRunAgent", () => {
     expect(agent).toBe("Atlas (Plan Executor)")
   })
 
+  it("prefers OPENCODE_AGENT over OPENCODE_DEFAULT_AGENT", () => {
+    // given
+    const config = createConfig({ default_run_agent: "prometheus" })
+    const env = {
+      OPENCODE_AGENT: "oracle",
+      OPENCODE_DEFAULT_AGENT: "Atlas",
+    }
+
+    // when
+    const agent = resolveRunAgent({ message: "test" }, config, env)
+
+    // then
+    expect(agent).toBe("oracle")
+  })
+
+  it("supports specialist agents from env and config inputs", () => {
+    // given
+    const env = { OPENCODE_AGENT: " explore " }
+
+    // when
+    const envAgent = resolveRunAgent({ message: "test" }, createConfig(), env)
+    const configAgent = resolveRunAgent(
+      { message: "test" },
+      createConfig({ default_run_agent: "oracle" }),
+      {}
+    )
+
+    // then
+    expect(envAgent).toBe("explore")
+    expect(configAgent).toBe("oracle")
+  })
+
   it("uses config agent over default", () => {
     // given
     const config = createConfig({ default_run_agent: "Prometheus" })
@@ -80,6 +112,17 @@ describe("resolveRunAgent", () => {
     // then
     expect(agent).toBe("Sisyphus (Ultraworker)")
   })
+
+  it("falls back when requested specialist agent is disabled", () => {
+    // given
+    const config = createConfig({ disabled_agents: ["oracle"] })
+
+    // when
+    const agent = resolveRunAgent({ message: "test", agent: "oracle" }, config, {})
+
+    // then
+    expect(agent).toBe("Sisyphus (Ultraworker)")
+  })
 })
 
 describe("waitForEventProcessorShutdown", () => {

src/config/schema/oh-my-opencode-config.ts

@@ -25,7 +25,7 @@ export const OhMyOpenCodeConfigSchema = z.object({
   $schema: z.string().optional(),
   /** Enable new task system (default: false) */
   new_task_system_enabled: z.boolean().optional(),
-  /** Default agent name for `oh-my-opencode run` (env: OPENCODE_DEFAULT_AGENT) */
+  /** Default agent name for `oh-my-opencode run` (env fallback: OPENCODE_DEFAULT_AGENT, after OPENCODE_AGENT) */
   default_run_agent: z.string().optional(),
   disabled_mcps: z.array(AnyMcpNameSchema).optional(),
   disabled_agents: z.array(z.string()).optional(),