feat: Agent Team

README.md

@@ -83,7 +83,8 @@ cp VersperClaw ~/.local/bin
     "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
     "ENABLE_TOOL_SEARCH": "true",
     "TAVILY_API_KEY": "",
-    "teammateMode": "tmux"
+  # "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0", default 1 
+    "teammateMode": "tmux" # or in-process
   }
 
   # set auto-dream config
@@ -141,7 +142,11 @@ cd desktop && bun run tauri dev
 
 ### Agent Team and View via Tmux
 
-
+<table align="center">
+  <tr>
+    <td><img src="assets/agentmate2.png"></td>
+  </tr>
+</table>
 
 ### Auto Compact & Dream & SubAgent
 

src/main.tsx

@@ -3824,8 +3824,8 @@ async function run(): Promise<CommanderCommand> {
       permissionMode: 'auto'
     }));
     program.addOption(new Option('--tasks [id]', '[ANT-ONLY] Tasks mode: watch for tasks and auto-process them. Optional id is used as both the task list ID and agent ID (defaults to "tasklist").').argParser(String).hideHelp());
-    program.option('--agent-teams', '[ANT-ONLY] Force Claude to use multi-agent mode for solving problems', () => true);
   }
+  program.option('--agent-teams', 'Force Claude to use multi-agent mode for solving problems', () => true);
   if (feature('TRANSCRIPT_CLASSIFIER')) {
     program.addOption(new Option('--enable-auto-mode', 'Opt in to auto mode').hideHelp());
   }

src/tools/shared/spawnMultiAgent.ts

@@ -3,6 +3,7 @@
  * Extracted from TeammateTool to allow reuse by AgentTool.
  */
 
+import { readlinkSync } from 'fs'
 import React from 'react'
 import {
   getChromeFlagOverride,
@@ -35,7 +36,7 @@ import {
   resetBackendDetection,
 } from '../../utils/swarm/backends/registry.js'
 import { getTeammateModeFromSnapshot } from '../../utils/swarm/backends/teammateModeSnapshot.js'
-import type { BackendType } from '../../utils/swarm/backends/types.js'
+import type { BackendType, PaneSpawnOptions } from '../../utils/swarm/backends/types.js'
 import { isPaneBackend } from '../../utils/swarm/backends/types.js'
 import {
   SWARM_SESSION_NAME,
@@ -49,8 +50,9 @@ import {
   type InProcessSpawnConfig,
   spawnInProcessTeammate,
 } from '../../utils/swarm/spawnInProcess.js'
-import { buildInheritedEnvVars } from '../../utils/swarm/spawnUtils.js'
+import { buildInheritedEnvMap, buildInheritedEnvVars } from '../../utils/swarm/spawnUtils.js'
 import {
+  mutateTeamFileAsync,
   readTeamFileAsync,
   sanitizeAgentName,
   sanitizeName,
@@ -185,6 +187,23 @@ async function ensureSession(sessionName: string): Promise<void> {
   }
 }
 
+/**
+ * Resolves the real executable path for the current process.
+ * In bun-compiled mode, process.execPath returns a bunfs virtual path
+ * (e.g., /$bunfs/root/VersperClaw). Uses /proc/self/exe on Linux to
+ * resolve the real binary path so spawned tmux panes can find it.
+ */
+function resolveRealExecPath(): string {
+  try {
+    if (process.platform === 'linux') {
+      return readlinkSync('/proc/self/exe')
+    }
+  } catch {
+    // Not on Linux or /proc not available — fall through
+  }
+  return process.execPath
+}
+
 /**
  * Gets the command to spawn a teammate.
  * For native builds (compiled binaries), use process.execPath.
@@ -194,7 +213,7 @@ function getTeammateCommand(): string {
   if (process.env[TEAMMATE_COMMAND_ENV_VAR]) {
     return process.env[TEAMMATE_COMMAND_ENV_VAR]
   }
-  return isInBundledMode() ? process.execPath : process.argv[1]!
+  return isInBundledMode() ? resolveRealExecPath() : process.argv[1]!
 }
 
 /**
@@ -381,23 +400,9 @@ async function handleSpawnSplitPane(
   // Assign a unique color to this teammate
   const teammateColor = assignTeammateColor(teammateId)
 
-  // Create a pane in the swarm view
-  // - Inside tmux: splits current window (leader on left, teammates on right)
-  // - In iTerm2 with it2: uses native iTerm2 split panes
-  // - Outside both: creates claude-swarm session with tiled teammates
-  const { paneId, isFirstTeammate } = await createTeammatePaneInSwarmView(
-    sanitizedName,
-    teammateColor,
-  )
-
-  // Enable pane border status on first teammate when inside tmux
-  // (outside tmux, this is handled in createTeammatePaneInSwarmView)
-  if (isFirstTeammate && insideTmux) {
-    await enablePaneBorderStatus()
-  }
-
   // Build the command to spawn Claude Code with teammate identity
-  // Note: We spawn without a prompt - initial instructions are sent via mailbox
+  // We build this BEFORE creating the pane so it can be passed directly
+  // to split-window (TmuxBackend), bypassing the shell intermediary.
   const binaryPath = getTeammateCommand()
 
   // Build teammate identity CLI args (replaces CLAUDE_CODE_* env vars)
@@ -414,7 +419,6 @@ async function handleSpawnSplitPane(
     .join(' ')
 
   // Build CLI flags to propagate to teammate
-  // Pass plan_mode_required to prevent inheriting bypass permissions
   let inheritedFlags = buildInheritedCliFlags({
     planModeRequired: plan_mode_required,
     permissionMode: appState.toolPermissionContext.mode,
@@ -422,26 +426,45 @@ async function handleSpawnSplitPane(
 
   // If teammate has a custom model, add --model flag (or replace inherited one)
   if (model) {
-    // Remove any inherited --model flag first
     inheritedFlags = inheritedFlags
       .split(' ')
       .filter((flag, i, arr) => flag !== '--model' && arr[i - 1] !== '--model')
       .join(' ')
-    // Add the teammate's model
     inheritedFlags = inheritedFlags
       ? `${inheritedFlags} --model ${quote([model])}`
       : `--model ${quote([model])}`
   }
 
   const flagsStr = inheritedFlags ? ` ${inheritedFlags}` : ''
-  // Propagate env vars that teammates need but may not inherit from tmux split-window shells.
-  // Includes CLAUDECODE, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, and API provider vars.
-  const envStr = buildInheritedEnvVars()
-  const spawnCommand = `cd ${quote([workingDir])} && env ${envStr} ${quote([binaryPath])} ${teammateArgs}${flagsStr}`
+  // Build env var map (skips vars already in settings.json / tmux global env)
+  const envMap = buildInheritedEnvMap()
+  const envStr = buildInheritedEnvVars() // string form for send-keys fallback
+  const spawnCommand = `${quote([binaryPath])} ${teammateArgs}${flagsStr}`
+
+  // Create a pane in the swarm view, passing the command directly
+  // TmuxBackend runs it via split-window <shell-command> (no shell needed).
+  // ITermBackend ignores spawnOptions and falls back to send-keys.
+  const { paneId, isFirstTeammate } = await createTeammatePaneInSwarmView(
+    sanitizedName,
+    teammateColor,
+    {
+      command: spawnCommand,
+      cwd: workingDir,
+      envVars: envMap,
+    } satisfies PaneSpawnOptions,
+  )
 
-  // Send the command to the new pane
-  // Use swarm socket when running outside tmux (external swarm session)
-  await sendCommandToPane(paneId, spawnCommand, !insideTmux)
+  // Enable pane border status on first teammate when inside tmux
+  if (isFirstTeammate && insideTmux) {
+    await enablePaneBorderStatus()
+  }
+
+  // For non-tmux backends (iTerm2), fall back to send-keys with the
+  // full shell command (cd + env prefix). TmuxBackend already ran it.
+  if (detectionResult.backend.type !== 'tmux') {
+    const shellCommand = `cd ${quote([workingDir])} && env ${envStr} ${spawnCommand}`
+    await sendCommandToPane(paneId, shellCommand, !insideTmux)
+  }
 
   // Determine session/window names for output
   const sessionName = insideTmux ? 'current' : SWARM_SESSION_NAME
@@ -485,28 +508,24 @@ async function handleSpawnSplitPane(
     toolUseId: context.toolUseId,
   })
 
-  // Register agent in the team file
-  const teamFile = await readTeamFileAsync(teamName)
-  if (!teamFile) {
-    throw new Error(
-      `Team "${teamName}" does not exist. Call spawnTeam first to create the team.`,
-    )
-  }
-  teamFile.members.push({
-    agentId: teammateId,
-    name: sanitizedName,
-    agentType: agent_type,
-    model,
-    prompt,
-    color: teammateColor,
-    planModeRequired: plan_mode_required,
-    joinedAt: Date.now(),
-    tmuxPaneId: paneId,
-    cwd: workingDir,
-    subscriptions: [],
-    backendType: detectionResult.backend.type,
+  // Register agent in the team file using atomic read-modify-write to avoid
+  // concurrent spawn clobbering other members.
+  await mutateTeamFileAsync(teamName, (teamFile) => {
+    teamFile.members.push({
+      agentId: teammateId,
+      name: sanitizedName,
+      agentType: agent_type,
+      model,
+      prompt,
+      color: teammateColor,
+      planModeRequired: plan_mode_required,
+      joinedAt: Date.now(),
+      tmuxPaneId: paneId,
+      cwd: workingDir,
+      subscriptions: [],
+      backendType: detectionResult.backend.type,
+    })
   })
-  await writeTeamFileAsync(teamName, teamFile)
 
   // Send initial instructions to teammate via mailbox
   // The teammate's inbox poller will pick this up and submit it as their first turn
@@ -699,28 +718,24 @@ async function handleSpawnSeparateWindow(
     toolUseId: context.toolUseId,
   })
 
-  // Register agent in the team file
-  const teamFile = await readTeamFileAsync(teamName)
-  if (!teamFile) {
-    throw new Error(
-      `Team "${teamName}" does not exist. Call spawnTeam first to create the team.`,
-    )
-  }
-  teamFile.members.push({
-    agentId: teammateId,
-    name: sanitizedName,
-    agentType: agent_type,
-    model,
-    prompt,
-    color: teammateColor,
-    planModeRequired: plan_mode_required,
-    joinedAt: Date.now(),
-    tmuxPaneId: paneId,
-    cwd: workingDir,
-    subscriptions: [],
-    backendType: 'tmux', // This handler always uses tmux directly
+  // Register agent in the team file using atomic read-modify-write to avoid
+  // concurrent spawn clobbering other members.
+  await mutateTeamFileAsync(teamName, (teamFile) => {
+    teamFile.members.push({
+      agentId: teammateId,
+      name: sanitizedName,
+      agentType: agent_type,
+      model,
+      prompt,
+      color: teammateColor,
+      planModeRequired: plan_mode_required,
+      joinedAt: Date.now(),
+      tmuxPaneId: paneId,
+      cwd: workingDir,
+      subscriptions: [],
+      backendType: 'tmux', // This handler always uses tmux directly
+    })
   })
-  await writeTeamFileAsync(teamName, teamFile)
 
   // Send initial instructions to teammate via mailbox
   // The teammate's inbox poller will pick this up and submit it as their first turn
@@ -985,28 +1000,24 @@ async function handleSpawnInProcess(
     }
   })
 
-  // Register agent in the team file
-  const teamFile = await readTeamFileAsync(teamName)
-  if (!teamFile) {
-    throw new Error(
-      `Team "${teamName}" does not exist. Call spawnTeam first to create the team.`,
-    )
-  }
-  teamFile.members.push({
-    agentId: teammateId,
-    name: sanitizedName,
-    agentType: agent_type,
-    model,
-    prompt,
-    color: teammateColor,
-    planModeRequired: plan_mode_required,
-    joinedAt: Date.now(),
-    tmuxPaneId: 'in-process',
-    cwd: getCwd(),
-    subscriptions: [],
-    backendType: 'in-process',
+  // Register agent in the team file using atomic read-modify-write to avoid
+  // concurrent spawn clobbering other members.
+  await mutateTeamFileAsync(teamName, (teamFile) => {
+    teamFile.members.push({
+      agentId: teammateId,
+      name: sanitizedName,
+      agentType: agent_type,
+      model,
+      prompt,
+      color: teammateColor,
+      planModeRequired: plan_mode_required,
+      joinedAt: Date.now(),
+      tmuxPaneId: 'in-process',
+      cwd: getCwd(),
+      subscriptions: [],
+      backendType: 'in-process',
+    })
   })
-  await writeTeamFileAsync(teamName, teamFile)
 
   // Note: Do NOT send the prompt via mailbox for in-process teammates.
   // In-process teammates receive the prompt directly via startInProcessTeammate().

src/utils/agentSwarmsEnabled.ts

@@ -1,42 +1,14 @@
-import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
-import { isEnvTruthy } from './envUtils.js'
-
-/**
- * Check if --agent-teams flag is provided via CLI.
- * Checks process.argv directly to avoid import cycles with bootstrap/state.
- * Note: The flag is only shown in help for ant users, but if external users
- * pass it anyway, it will work (subject to the killswitch).
- */
-function isAgentTeamsFlagSet(): boolean {
-  return process.argv.includes('--agent-teams')
-}
-
 /**
  * Centralized runtime check for agent teams/teammate features.
  * This is the single gate that should be checked everywhere teammates
  * are referenced (prompts, code, tools isEnabled, UI, etc.).
  *
- * Ant builds: always enabled.
- * External builds require both:
- * 1. Opt-in via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var OR --agent-teams flag
- * 2. GrowthBook gate 'tengu_amber_flint' enabled (killswitch)
+ * Free-code: always enabled by default.
+ * Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 to explicitly disable.
  */
 export function isAgentSwarmsEnabled(): boolean {
-  // Ant: always on
-  if (process.env.USER_TYPE === 'ant') {
-    return true
-  }
-
-  // External: require opt-in via env var or --agent-teams flag
-  if (
-    !isEnvTruthy(process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) &&
-    !isAgentTeamsFlagSet()
-  ) {
-    return false
-  }
-
-  // Killswitch — always respected for external users
-  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_flint', true)) {
+  // Explicit opt-out
+  if (process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === '0') {
     return false
   }
 

src/utils/swarm/backends/ITermBackend.ts

@@ -3,7 +3,7 @@ import { logForDebugging } from '../../../utils/debug.js'
 import { execFileNoThrow } from '../../../utils/execFileNoThrow.js'
 import { IT2_COMMAND, isInITerm2, isIt2CliAvailable } from './detection.js'
 import { registerITermBackend } from './registry.js'
-import type { CreatePaneResult, PaneBackend, PaneId } from './types.js'
+import type { CreatePaneResult, PaneBackend, PaneId, PaneSpawnOptions } from './types.js'
 
 // Track session IDs for teammates
 const teammateSessionIds: string[] = []
@@ -114,6 +114,7 @@ export class ITermBackend implements PaneBackend {
   async createTeammatePaneInSwarmView(
     name: string,
     color: AgentColorName,
+    _spawnOptions?: PaneSpawnOptions,
   ): Promise<CreatePaneResult> {
     logForDebugging(
       `[ITermBackend] createTeammatePaneInSwarmView called for ${name} with color ${color}`,

src/utils/swarm/backends/TmuxBackend.ts

@@ -17,7 +17,7 @@ import {
   isTmuxAvailable,
 } from './detection.js'
 import { registerTmuxBackend } from './registry.js'
-import type { CreatePaneResult, PaneBackend, PaneId } from './types.js'
+import type { CreatePaneResult, PaneBackend, PaneId, PaneSpawnOptions } from './types.js'
 
 // Track whether the first pane has been used for external swarm session
 let firstPaneUsedForExternal = false
@@ -129,6 +129,7 @@ export class TmuxBackend implements PaneBackend {
   async createTeammatePaneInSwarmView(
     name: string,
     color: AgentColorName,
+    spawnOptions?: PaneSpawnOptions,
   ): Promise<CreatePaneResult> {
     const releaseLock = await acquirePaneCreationLock()
 
@@ -136,7 +137,7 @@ export class TmuxBackend implements PaneBackend {
       const insideTmux = await this.isRunningInside()
 
       if (insideTmux) {
-        return await this.createTeammatePaneWithLeader(name, color)
+        return await this.createTeammatePaneWithLeader(name, color, spawnOptions)
       }
 
       return await this.createTeammatePaneExternal(name, color)
@@ -547,10 +548,13 @@ export class TmuxBackend implements PaneBackend {
 
   /**
    * Creates a teammate pane when running inside tmux (with leader).
+   * If spawnOptions.command is provided, runs it directly in the pane
+   * via split-window <shell-command>, bypassing the shell intermediary.
    */
   private async createTeammatePaneWithLeader(
     teammateName: string,
     teammateColor: AgentColorName,
+    spawnOptions?: PaneSpawnOptions,
   ): Promise<CreatePaneResult> {
     const currentPaneId = await this.getCurrentPaneId()
     const windowTarget = await this.getCurrentWindowTarget()
@@ -565,6 +569,24 @@ export class TmuxBackend implements PaneBackend {
     }
     const isFirstTeammate = paneCount === 1
 
+    // Build split-window args
+    // If spawnOptions.command is provided, pass it directly as the
+    // shell-command argument to split-window. This avoids the bash
+    // intermediary and the subsequent send-keys step.
+    const splitArgs: string[] = []
+    if (spawnOptions?.command) {
+      // Working directory via tmux -c flag (no need for cd ... &&)
+      if (spawnOptions.cwd) {
+        splitArgs.push('-c', spawnOptions.cwd)
+      }
+      // Environment vars via tmux -e flags (no need for env KEY=VALUE prefix)
+      if (spawnOptions.envVars) {
+        for (const [key, val] of Object.entries(spawnOptions.envVars)) {
+          splitArgs.push('-e', `${key}=${val}`)
+        }
+      }
+    }
+
     let splitResult
     if (isFirstTeammate) {
       // First teammate: split horizontally from the leader pane
@@ -578,6 +600,8 @@ export class TmuxBackend implements PaneBackend {
         '-P',
         '-F',
         '#{pane_id}',
+        ...splitArgs,
+        ...(spawnOptions?.command ? [spawnOptions.command] : []),
       ])
     } else {
       // Additional teammates: split from an existing teammate pane
@@ -607,6 +631,8 @@ export class TmuxBackend implements PaneBackend {
         '-P',
         '-F',
         '#{pane_id}',
+        ...splitArgs,
+        ...(spawnOptions?.command ? [spawnOptions.command] : []),
       ])
     }
 
@@ -623,8 +649,11 @@ export class TmuxBackend implements PaneBackend {
     await this.setPaneTitle(paneId, teammateName, teammateColor)
     await this.rebalancePanesWithLeader(windowTarget)
 
-    // Wait for shell to initialize before returning, so commands can be sent immediately
-    await waitForPaneShellReady()
+    // If we passed a command directly, there's no shell waiting for
+    // input — skip the shell-init delay.
+    if (!spawnOptions?.command) {
+      await waitForPaneShellReady()
+    }
 
     return { paneId, isFirstTeammate }
   }
@@ -635,6 +664,7 @@ export class TmuxBackend implements PaneBackend {
   private async createTeammatePaneExternal(
     teammateName: string,
     teammateColor: AgentColorName,
+    spawnOptions?: PaneSpawnOptions,
   ): Promise<CreatePaneResult> {
     const { windowTarget, paneId: firstPaneId } =
       await this.createExternalSwarmSession()
@@ -645,6 +675,19 @@ export class TmuxBackend implements PaneBackend {
     }
     const isFirstTeammate = !firstPaneUsedForExternal && paneCount === 1
 
+    // Build split-window args (same logic as createTeammatePaneWithLeader)
+    const splitArgs: string[] = []
+    if (spawnOptions?.command) {
+      if (spawnOptions.cwd) {
+        splitArgs.push('-c', spawnOptions.cwd)
+      }
+      if (spawnOptions.envVars) {
+        for (const [key, val] of Object.entries(spawnOptions.envVars)) {
+          splitArgs.push('-e', `${key}=${val}`)
+        }
+      }
+    }
+
     let paneId: string
 
     if (isFirstTeammate) {
@@ -655,6 +698,12 @@ export class TmuxBackend implements PaneBackend {
       )
 
       await this.enablePaneBorderStatus(windowTarget, true)
+
+      // First pane in external session can't use split-window with command,
+      // so fall back to send-keys.
+      if (spawnOptions?.command) {
+        await this.sendCommandToPane(paneId, spawnOptions.command, true)
+      }
     } else {
       const listResult = await runTmuxInSwarm([
         'list-panes',
@@ -695,8 +744,9 @@ export class TmuxBackend implements PaneBackend {
     await this.setPaneTitle(paneId, teammateName, teammateColor, true)
     await this.rebalancePanesTiled(windowTarget)
 
-    // Wait for shell to initialize before returning, so commands can be sent immediately
-    await waitForPaneShellReady()
+    if (!spawnOptions?.command) {
+      await waitForPaneShellReady()
+    }
 
     return { paneId, isFirstTeammate }
   }

src/utils/swarm/backends/types.ts

@@ -31,6 +31,21 @@ export type CreatePaneResult = {
   isFirstTeammate: boolean
 }
 
+/**
+ * Optional parameters for directly executing a command in a newly created pane,
+ * bypassing the shell intermediary and subsequent send-keys step.
+ * Supported by TmuxBackend via split-window <shell-command>; ignored by
+ * ITermBackend (falls back to send-keys).
+ */
+export type PaneSpawnOptions = {
+  /** The command to execute directly in the pane (instead of a shell) */
+  command: string
+  /** Working directory for the pane (tmux -c flag) */
+  cwd: string
+  /** Environment variables to set on the pane (tmux -e flags) */
+  envVars?: Record<string, string>
+}
+
 /**
  * Interface for pane management backends.
  * Abstracts operations for creating and managing terminal panes
@@ -66,11 +81,14 @@ export type PaneBackend = {
    *
    * @param name - The teammate's name for display
    * @param color - The color to use for the pane border/title
+   * @param spawnOptions - Optional command to run directly in the pane
+   *   (TmuxBackend only; ITermBackend ignores this and falls back to send-keys)
    * @returns The pane ID and whether this was the first teammate
    */
   createTeammatePaneInSwarmView(
     name: string,
     color: AgentColorName,
+    spawnOptions?: PaneSpawnOptions,
   ): Promise<CreatePaneResult>
 
   /**

src/utils/swarm/spawnUtils.ts

@@ -9,12 +9,35 @@ import {
   getMainLoopModelOverride,
   getSessionBypassPermissionsMode,
 } from '../../bootstrap/state.js'
+import { readlinkSync } from 'fs'
 import { quote } from '../bash/shellQuote.js'
 import { isInBundledMode } from '../bundledMode.js'
 import type { PermissionMode } from '../permissions/PermissionMode.js'
 import { getTeammateModeFromSnapshot } from './backends/teammateModeSnapshot.js'
 import { TEAMMATE_COMMAND_ENV_VAR } from './constants.js'
 
+/**
+ * Resolves the real executable path for the current process.
+ *
+ * In bun-compiled mode, process.execPath may return a bunfs virtual path
+ * (e.g., /$bunfs/root/VersperClaw) that only exists within the bun runtime.
+ * When a tmux pane tries to execute this path in a regular shell, it fails
+ * with "No such file or directory".
+ *
+ * Fix: use /proc/self/exe on Linux to resolve the real binary path.
+ * On unsupported platforms, falls back to process.execPath.
+ */
+function resolveRealExecPath(): string {
+  try {
+    if (process.platform === 'linux') {
+      return readlinkSync('/proc/self/exe')
+    }
+  } catch {
+    // Not on Linux or /proc not available — fall through
+  }
+  return process.execPath
+}
+
 /**
  * Gets the command to use for spawning teammate processes.
  * Uses TEAMMATE_COMMAND_ENV_VAR if set, otherwise falls back to the
@@ -24,7 +47,7 @@ export function getTeammateCommand(): string {
   if (process.env[TEAMMATE_COMMAND_ENV_VAR]) {
     return process.env[TEAMMATE_COMMAND_ENV_VAR]
   }
-  return isInBundledMode() ? process.execPath : process.argv[1]!
+  return isInBundledMode() ? resolveRealExecPath() : process.argv[1]!
 }
 
 /**
@@ -141,19 +164,42 @@ const TEAMMATE_ENV_VARS = [
 ] as const
 
 /**
- * Builds the `env KEY=VALUE ...` string for teammate spawn commands.
- * Always includes CLAUDECODE=1 and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,
- * plus any provider/config env vars that are set in the current process.
+ * Builds a map of environment variables for teammate spawn commands.
+ * Skips CLAUDECODE and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS if already set
+ * in the current environment (e.g., from settings.json env or tmux global env).
+ *
+ * Returns a Record<string, string> suitable for tmux -e flags or manual
+ * env KEY=VALUE construction.
  */
-export function buildInheritedEnvVars(): string {
-  const envVars = ['CLAUDECODE=1', 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1']
+export function buildInheritedEnvMap(): Record<string, string> {
+  const envMap: Record<string, string> = {}
+
+  // Only hardcode these if NOT already set in process env — the user may
+  // have them in ~/.claude/settings.json env, tmux set-environment, etc.
+  if (!process.env.CLAUDECODE) {
+    envMap.CLAUDECODE = '1'
+  }
+  if (!process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) {
+    envMap.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1'
+  }
 
   for (const key of TEAMMATE_ENV_VARS) {
     const value = process.env[key]
     if (value !== undefined && value !== '') {
-      envVars.push(`${key}=${quote([value])}`)
+      envMap[key] = value
     }
   }
 
-  return envVars.join(' ')
+  return envMap
+}
+
+/**
+ * Builds the `env KEY=VALUE ...` string for teammate spawn commands.
+ * Delegates to buildInheritedEnvMap() for the values.
+ */
+export function buildInheritedEnvVars(): string {
+  const envMap = buildInheritedEnvMap()
+  return Object.entries(envMap)
+    .map(([key, value]) => `${key}=${quote([value])}`)
+    .join(' ')
 }

src/utils/swarm/teamHelpers.ts

@@ -10,6 +10,7 @@ import { execFileNoThrowWithCwd } from '../execFileNoThrow.js'
 import { gitExe } from '../git.js'
 import { lazySchema } from '../lazySchema.js'
 import type { PermissionMode } from '../permissions/PermissionMode.js'
+import * as lockfile from '../lockfile.js'
 import { jsonParse, jsonStringify } from '../slowOperations.js'
 import { getTasksDir, notifyTasksUpdated } from '../tasks.js'
 import { getAgentName, getTeamName, isTeammate } from '../teammate.js'
@@ -181,6 +182,52 @@ export async function writeTeamFileAsync(
   await writeFile(getTeamFilePath(teamName), jsonStringify(teamFile, null, 2))
 }
 
+/**
+ * Atomically read-modify-write a team file under a file lock.
+ * Use this for concurrent member updates such as teammate spawning.
+ * Ensures parallel spawn operations don't clobber each other's member registrations.
+ */
+export async function mutateTeamFileAsync(
+  teamName: string,
+  mutator: (teamFile: TeamFile) => TeamFile | void,
+): Promise<TeamFile> {
+  const teamDir = getTeamDir(teamName)
+  const teamFilePath = getTeamFilePath(teamName)
+  const lockFilePath = `${teamFilePath}.lock`
+
+  await mkdir(teamDir, { recursive: true })
+  // Ensure the file exists (create if not, ignore if already exists)
+  try {
+    await writeFile(teamFilePath, '{}', { encoding: 'utf-8', flag: 'wx' })
+  } catch (e) {
+    if (getErrnoCode(e) !== 'EEXIST') {
+      throw e
+    }
+  }
+
+  const release = await lockfile.lock(teamFilePath, {
+    lockfilePath: lockFilePath,
+    retries: {
+      retries: 10,
+      minTimeout: 5,
+      maxTimeout: 100,
+    },
+  })
+
+  try {
+    const current = await readTeamFileAsync(teamName)
+    if (!current || !Array.isArray(current.members)) {
+      throw new Error(`Team "${teamName}" does not exist`)
+    }
+
+    const next = mutator(current) ?? current
+    await writeFile(teamFilePath, jsonStringify(next, null, 2))
+    return next
+  } finally {
+    await release()
+  }
+}
+
 /**
  * Removes a teammate from the team file by agent ID or name.
  * Used by the leader when processing shutdown approvals.

src/utils/swarm/teammateLayoutManager.ts

@@ -1,7 +1,7 @@
 import type { AgentColorName } from '../../tools/AgentTool/agentColorManager.js'
 import { AGENT_COLORS } from '../../tools/AgentTool/agentColorManager.js'
 import { detectAndGetBackend } from './backends/registry.js'
-import type { PaneBackend } from './backends/types.js'
+import type { PaneBackend, PaneSpawnOptions } from './backends/types.js'
 
 // Track color assignments for teammates (persisted per session)
 const teammateColorAssignments = new Map<string, AgentColorName>()
@@ -76,9 +76,10 @@ export async function isInsideTmux(): Promise<boolean> {
 export async function createTeammatePaneInSwarmView(
   teammateName: string,
   teammateColor: AgentColorName,
+  spawnOptions?: PaneSpawnOptions,
 ): Promise<{ paneId: string; isFirstTeammate: boolean }> {
   const backend = await getBackend()
-  return backend.createTeammatePaneInSwarmView(teammateName, teammateColor)
+  return backend.createTeammatePaneInSwarmView(teammateName, teammateColor, spawnOptions)
 }
 
 /**