feat(cli): add --agent flag to override agent plugin at spawn time

Allows starting sessions with a different agent without changing config:
  ao spawn ao --agent codex
  ao spawn ao --agent codex INT-1234

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/cli/src/commands/spawn.ts

@@ -11,6 +11,7 @@ async function spawnSession(
   projectId: string,
   issueId?: string,
   openTab?: boolean,
+  agent?: string,
 ): Promise<string> {
   const spinner = ora("Creating session").start();
 
@@ -21,6 +22,7 @@ async function spawnSession(
     const session = await sm.spawn({
       projectId,
       issueId,
+      agent,
     });
 
     spinner.succeed(`Session ${chalk.green(session.id)} created`);
@@ -58,7 +60,8 @@ export function registerSpawn(program: Command): void {
     .argument("<project>", "Project ID from config")
     .argument("[issue]", "Issue identifier (e.g. INT-1234, #42) - must exist in tracker")
     .option("--open", "Open session in terminal tab")
-    .action(async (projectId: string, issueId: string | undefined, opts: { open?: boolean }) => {
+    .option("--agent <name>", "Override the agent plugin (e.g. codex, claude-code)")
+    .action(async (projectId: string, issueId: string | undefined, opts: { open?: boolean; agent?: string }) => {
       const config = loadConfig();
       if (!config.projects[projectId]) {
         console.error(
@@ -70,7 +73,7 @@ export function registerSpawn(program: Command): void {
       }
 
       try {
-        await spawnSession(config, projectId, issueId, opts.open);
+        await spawnSession(config, projectId, issueId, opts.open, opts.agent);
       } catch (err) {
         console.error(chalk.red(`✗ ${err}`));
         process.exit(1);

packages/core/src/session-manager.ts

@@ -322,6 +322,16 @@ export function createSessionManager(deps: SessionManagerDeps): SessionManager {
     if (!plugins.runtime) {
       throw new Error(`Runtime plugin '${project.runtime ?? config.defaults.runtime}' not found`);
     }
+
+    // Allow --agent override to swap the agent plugin for this session
+    if (spawnConfig.agent) {
+      const overrideAgent = registry.get<Agent>("agent", spawnConfig.agent);
+      if (!overrideAgent) {
+        throw new Error(`Agent plugin '${spawnConfig.agent}' not found`);
+      }
+      plugins.agent = overrideAgent;
+    }
+
     if (!plugins.agent) {
       throw new Error(`Agent plugin '${project.agent ?? config.defaults.agent}' not found`);
     }

packages/core/src/types.ts

@@ -176,6 +176,8 @@ export interface SessionSpawnConfig {
   issueId?: string;
   branch?: string;
   prompt?: string;
+  /** Override the agent plugin for this session (e.g. "codex", "claude-code") */
+  agent?: string;
 }
 
 /** Config for creating an orchestrator session */