团队与 Swarm

async call(input, context) {
  const { setAppState, getAppState } = context
  const appState = getAppState()

  // Guard: one team per leader at a time
  const existingTeam = appState.teamContext?.teamName
  if (existingTeam) {
    throw new Error(
      `Already leading team "${existingTeam}". Use TeamDelete first.`
    )
  }

  // Deduplicate name
  const finalTeamName = generateUniqueTeamName(team_name)
  const leadAgentId   = formatAgentId(TEAM_LEAD_NAME, finalTeamName)

  const teamFile: TeamFile = {
    name: finalTeamName,
    createdAt: Date.now(),
    leadAgentId,
    leadSessionId: getSessionId(),
    members: [{
      agentId:      leadAgentId,
      name:         TEAM_LEAD_NAME,     // "team-lead"
      agentType:    leadAgentType,
      model:        leadModel,
      joinedAt:     Date.now(),
      tmuxPaneId:   '',
      cwd:          getCwd(),
      subscriptions: [],
    }],
  }

  await writeTeamFileAsync(finalTeamName, teamFile)
  registerTeamForSessionCleanup(finalTeamName)

  await resetTaskList(taskListId)
  await ensureTasksDir(taskListId)
  setLeaderTeamName(sanitizeName(finalTeamName))

  setAppState(prev => ({
    ...prev,
    teamContext: {
      teamName:    finalTeamName,
      teamFilePath,
      leadAgentId,
      teammates: {
        [leadAgentId]: {
          name:         TEAM_LEAD_NAME,
          color:        assignTeammateColor(leadAgentId),
          spawnedAt:    Date.now(),
          ...
        }
      }
    }
  }))
}

type TeamFile = {
  name:            string           // canonical team name
  description?:    string
  createdAt:       number           // epoch ms
  leadAgentId:     string           // "team-lead@my-team"
  leadSessionId?:  string           // session UUID of the leader
  hiddenPaneIds?:  string[]         // pane IDs moved to hidden window
  teamAllowedPaths?: TeamAllowedPath[]  // shared "always allow" edit rules
  members: Array<{
    agentId:        string   // "researcher@my-team"
    name:           string   // "researcher" — used for SendMessage
    agentType?:     string
    model?:         string
    prompt?:        string
    color?:         string
    planModeRequired?: boolean
    joinedAt:       number
    tmuxPaneId:     string   // "%3" tmux pane or iTerm session UUID
    cwd:            string
    worktreePath?:  string   // git worktree if isolated
    sessionId?:     string   // Claude session UUID
    subscriptions:  string[]
    backendType?:   'tmux' | 'iterm2' | 'in-process'
    isActive?:      boolean  // false = idle, undefined/true = running
    mode?:          PermissionMode
  }>
}

// Priority order (first match wins, cached for the session)

// 1. Running INSIDE tmux? Always use tmux.
if (await isInsideTmux()) {
  return { backend: createTmuxBackend(), isNative: true }
}

// 2. In iTerm2 with it2 CLI? Use iTerm2 (unless user prefers tmux).
if (isInITerm2()) {
  if (!getPreferTmuxOverIterm2()) {
    const it2Available = await isIt2CliAvailable()
    if (it2Available) {
      return { backend: createITermBackend(), isNative: true }
    }
  }
  // Fallback to tmux as external session if tmux is installed
  if (await isTmuxAvailable()) {
    return { backend: createTmuxBackend(), isNative: false, needsIt2Setup: true }
  }
}

// 3. Standalone terminal with tmux installed
if (await isTmuxAvailable()) {
  return { backend: createTmuxBackend(), isNative: false }
}

// 4. Nothing available → throw with platform-specific install instructions
throw new Error(getTmuxInstallInstructions())

检测使用捕获的环境变量 模块加载时间 — TMUX, TMUX_PANE, TERM_PROGRAM， 和 ITERM_SESSION_ID - 所以 shell 或后来的代码覆盖它们没有效果。

The it2 有意运行可用性检查 it2 session list (not it2 --version） 因为 --version 即使禁用 iTerm2 Python API，也会退出 0，这将导致窗格分割稍后静默失败。

在 tmux 内部（领导者位于窗格中）： 第一个队友水平分割领导者的窗格 -l 70% 所以领导者保留了 30% 的窗口。 其他队友从现有队友窗格中垂直/水平交替分开，然后 select-layout main-vertical 重新平衡右侧。

tmux 之外（独立终端）： 在 PID 范围的套接字上创建单独的 tmux 服务器（claude-swarm-<pid>）。 一个 claude-swarm 与一个会话 swarm-view 窗口已创建。 队友采用平铺布局。 用户可以使用以下方式附加到此会话 tmux -L claude-swarm-<pid> attach.

// Internal tmux socket name prevents conflicts between multiple Claude instances
export function getSwarmSocketName(): string {
  return `claude-swarm-${process.pid}`
}

窗格创建通过基于承诺的互斥体进行序列化（acquirePaneCreationLock()）以防止并行生成多个队友时出现竞争状况。 创建每个窗格后，后端会休眠 200 毫秒，以允许 shell（zsh/bash、oh-my-zsh 等）在发送 Claude 命令之前完成初始化。

iTerm2 后端跟踪模块级数组中的窗格会话 UUID。 当产生额外的队友时，它通过以下方式定位最后一个已知的会话 UUID it2 session split -s <uuid>.

如果用户手动关闭窗格（Cmd+W），则下一次生成将失败并显示非零退出代码。 后端通过运行确认会话确实已死亡 it2 session list 并检查 UUID。 如果丢失，它会从数组中删除过时的 ID 并重试。 这个循环是有界的——每次迭代都会将数组缩小一，因此最坏情况下它会终止 N+1 iterations.

while (true) {
  const splitResult = await runIt2(splitArgs)
  if (splitResult.code !== 0 && targetedTeammateId) {
    const listResult = await runIt2(['session', 'list'])
    if (!listResult.stdout.includes(targetedTeammateId)) {
      teammateSessionIds.splice(idx, 1)   // prune dead session
      continue                               // retry with next-to-last
    }
    throw new Error(...)  // systemic failure — surface it
  }
  break
}

进程内队友在领导者的 Node.js 进程内运行。 他们共享 API 客户端和 MCP 连接，但完全隔离 身份背景 via AsyncLocalStorage — 每个队友都有自己的代理名称、团队名称、颜色和 AbortController。

生成流程：

1. spawnInProcessTeammate() 创建一个 TeammateContext 和一个独立的 AbortController （与领导者无关），注册一个 InProcessTeammateTaskState in AppState.tasks，并返回。
2. InProcessBackend.spawn() 然后打电话 startInProcessTeammate() 作为一劳永逸的方式——代理循环在后台的事件循环上运行。
3. 杀死用途 abortController.abort() 而不是杀死进程，并且任务状态转换为 'killed'.

// Teammates get an independent abort controller — interrupting the leader
// does NOT abort active teammates.
const abortController = createAbortController()

// Strip parent messages — teammates start with an empty conversation
toolUseContext: { ...this.context, messages: [] }

// Flags always forwarded if applicable:
'--dangerously-skip-permissions'  // if bypassPermissions mode active
'--permission-mode acceptEdits'   // if acceptEdits mode active
'--model <model>'                 // if set via CLI
'--settings <path>'               // if set via CLI
'--plugin-dir <dir>'              // for each inline plugin
'--teammate-mode <mode>'          // so nested spawns use same mode
'--chrome / --no-chrome'          // if set explicitly

// Env vars always set:
CLAUDECODE=1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
CLAUDE_CODE_AGENT_COLOR=<color>   // assigned color for pane border

// Env vars forwarded if present in parent process:
CLAUDE_CODE_USE_BEDROCK  CLAUDE_CODE_USE_VERTEX  ANTHROPIC_BASE_URL
CLAUDE_CONFIG_DIR  CLAUDE_CODE_REMOTE  HTTPS_PROXY  ...

Plan模式比较特殊：if planModeRequired=true，绕过权限标志是 not 即使领导者设置了它们也会传播。 安全胜于便利。

type SwarmPermissionRequest = {
  id:                  string   // "perm-<ts>-<random>"
  workerId:            string   // "researcher@my-team"
  workerName:          string
  workerColor?:        string
  teamName:            string
  toolName:            string   // e.g. "Edit"
  toolUseId:           string
  description:         string   // human-readable summary
  input:               Record<string, unknown>
  permissionSuggestions: unknown[]
  status:              'pending' | 'approved' | 'rejected'
  resolvedBy?:         'worker' | 'leader'
  resolvedAt?:         number
  feedback?:           string
  updatedInput?:       Record<string, unknown>
  permissionUpdates?:  unknown[]
  createdAt:           number
}

对挂起目录的写操作使用 .lock 文件与 proper-lockfile 语义，以便并发工作人员不会破坏彼此的请求。

对于正在处理的队友，权限提示直接显示在领导者的终端 UI 中，而不是通过文件系统。 桥接模块（leaderPermissionBridge.ts) 是一个模块级注册表，用于存储 REPL 在启动时注册的 React setter 函数：

// In leaderPermissionBridge.ts — no React dependency
let registeredSetter: SetToolUseConfirmQueueFn | null = null

export function registerLeaderToolUseConfirmQueue(setter): void {
  registeredSetter = setter
}
export function getLeaderToolUseConfirmQueue() {
  return registeredSetter
}

进程内运行程序调用 getLeaderToolUseConfirmQueue() 当它需要显示确认对话框时，完全绕过基于文件的权限系统。

async call(_input, context) {
  const teamName = getAppState().teamContext?.teamName

  if (teamName) {
    const teamFile = readTeamFile(teamName)
    const nonLeadMembers = teamFile.members
      .filter(m => m.name !== TEAM_LEAD_NAME)
    const activeMembers = nonLeadMembers
      .filter(m => m.isActive !== false)   // idle = false, running = true/undefined

    if (activeMembers.length > 0) {
      return { success: false, message: `Cannot cleanup: ${memberNames} still active` }
    }

    await cleanupTeamDirectories(teamName)  // teams/ + tasks/ + git worktrees
    unregisterTeamForSessionCleanup(teamName)
    clearTeammateColors()
    clearLeaderTeamName()
  }

  setAppState(prev => ({
    ...prev,
    teamContext: undefined,
    inbox: { messages: [] },   // flush queued messages
  }))
}

在列表视图中，按循环模式键调用 cycleAllTeammateModes() 它使用 setMultipleMemberModes() 对于原子多写，防止顺序单写的 TOCTOU 问题。

在详细视图中，它仅循环选定的队友 setMemberMode()，然后发送一个 mode_set_request 消息发送到队友的邮箱，以便在没有文件监视轮询延迟的情况下通知正在运行的进程。

// Atomic update of all member modes in one config.json write
setMultipleMemberModes(teamName, [
  { memberName: 'researcher', mode: 'acceptEdits' },
  { memberName: 'tester',     mode: 'acceptEdits' },
])