team-mode: centralize member session coordination

Author: code-yeongyu

src/features/team-mode/member-guidance.ts

@@ -0,0 +1,29 @@
+import type { TeamModeConfig } from "../../config/schema/team-mode"
+
+export function buildTeammateCommunicationAddendum(config: TeamModeConfig): string {
+  const delegateTaskGuidance = config.member_delegate_task_budget > 0
+    ? `- delegate-task: You may use this for bounded side work when needed. You have a budget of ${config.member_delegate_task_budget} calls for this team run.`
+    : "- delegate-task: Do not call this. Member delegate budget is disabled for this team run."
+
+  return `
+# Team Communication
+
+You are running as a team member. Your text responses are NOT visible to other team members or the lead.
+
+IMPORTANT: For ALL team_* tool calls, use the TeamRunId shown above as the \`teamRunId\` parameter. Do NOT use the team name.
+
+Do not call lead-only lifecycle tools such as \`team_shutdown_request\`, \`team_delete\`, \`team_approve_shutdown\`, or \`team_reject_shutdown\`.
+
+Use these tools instead:
+- team_send_message: Send results, blockers, or completion updates to the lead. Use \`to: "lead"\` for the lead, \`to: "<name>"\` for a specific member. Include \`summary\` and \`references\` when they help the lead triage quickly.
+- team_task_update: Update your task status. Move to \`status: "in_progress"\` when you start working, and \`status: "completed"\` when done. \`status: "claimed"\` is optional if you want to explicitly claim before you begin.
+- team_task_list: See all team tasks and their status.
+- team_task_get: Get details of a specific task.
+${delegateTaskGuidance}
+
+When you finish your assigned work, ALWAYS:
+1. Send your results to lead via team_send_message
+2. Mark your task as completed via team_task_update
+3. Send a completion message to lead so the lead can decide whether to request shutdown
+`
+}

src/features/team-mode/member-session-resolution.ts

@@ -0,0 +1,63 @@
+import type { TeamModeConfig } from "../../config/schema/team-mode"
+import { log } from "../../shared/logger"
+import { lookupTeamSession } from "./team-session-registry"
+import { listActiveTeams, loadRuntimeState } from "./team-state-store/store"
+
+export type ResolvedMemberSession = {
+  teamRunId: string
+  memberName: string
+}
+
+export async function findResolvedMemberSession(
+  sessionID: string,
+  config: TeamModeConfig,
+  logContext: string,
+): Promise<ResolvedMemberSession | null> {
+  const registryEntry = lookupTeamSession(sessionID)
+  if (registryEntry?.role === "member") {
+    try {
+      const runtimeState = await loadRuntimeState(registryEntry.teamRunId, config)
+      const memberEntry = runtimeState.members.find(
+        (member) => member.name === registryEntry.memberName
+          && (member.sessionId === undefined || member.sessionId === sessionID),
+      )
+
+      if (memberEntry !== undefined) {
+        return {
+          teamRunId: runtimeState.teamRunId,
+          memberName: memberEntry.name,
+        }
+      }
+    } catch (error) {
+      log(`${logContext} registry lookup failed`, {
+        event: `${logContext}-registry-error`,
+        teamRunId: registryEntry.teamRunId,
+        sessionID,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  const activeTeams = await listActiveTeams(config)
+  for (const activeTeam of activeTeams) {
+    try {
+      const runtimeState = await loadRuntimeState(activeTeam.teamRunId, config)
+      const memberEntry = runtimeState.members.find((member) => member.sessionId === sessionID)
+      if (memberEntry !== undefined) {
+        return {
+          teamRunId: runtimeState.teamRunId,
+          memberName: memberEntry.name,
+        }
+      }
+    } catch (error) {
+      log(`${logContext} skipped runtime`, {
+        event: `${logContext}-runtime-error`,
+        teamRunId: activeTeam.teamRunId,
+        sessionID,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  return null
+}

src/features/team-mode/member-session-routing.ts

@@ -0,0 +1,67 @@
+import { stripAgentListSortPrefix } from "../../shared/agent-display-names"
+import { applySessionPromptParams } from "../../shared/session-prompt-params-helpers"
+import { SessionCategoryRegistry } from "../../shared/session-category-registry"
+import type { RuntimeStateMember } from "./types"
+
+type PromptGenerationModel = {
+  reasoningEffort?: string
+  temperature?: number
+  top_p?: number
+  maxTokens?: number
+  thinking?: { type: "enabled" | "disabled"; budgetTokens?: number }
+}
+
+export type TeamMemberPromptBody = {
+  parts: Array<{ type: "text"; text: string }>
+  agent?: string
+  model?: { providerID: string; modelID: string }
+  variant?: string
+  temperature?: number
+  topP?: number
+  maxOutputTokens?: number
+  options?: Record<string, unknown>
+}
+
+function buildPromptGenerationParams(model: PromptGenerationModel | undefined): Omit<TeamMemberPromptBody, "parts" | "agent" | "model" | "variant"> {
+  if (!model) {
+    return {}
+  }
+
+  const promptOptions: Record<string, unknown> = {
+    ...(model.reasoningEffort ? { reasoningEffort: model.reasoningEffort } : {}),
+    ...(model.thinking ? { thinking: model.thinking } : {}),
+  }
+
+  return {
+    ...(model.temperature !== undefined ? { temperature: model.temperature } : {}),
+    ...(model.top_p !== undefined ? { topP: model.top_p } : {}),
+    ...(model.maxTokens !== undefined ? { maxOutputTokens: model.maxTokens } : {}),
+    ...(Object.keys(promptOptions).length > 0 ? { options: promptOptions } : {}),
+  }
+}
+
+export function applyMemberSessionRouting(sessionID: string, member: RuntimeStateMember): void {
+  if (member.category) {
+    SessionCategoryRegistry.register(sessionID, member.category)
+  }
+
+  applySessionPromptParams(sessionID, member.model)
+}
+
+export function buildMemberPromptBody(member: RuntimeStateMember, text: string): TeamMemberPromptBody {
+  const normalizedAgent = member.subagent_type ? stripAgentListSortPrefix(member.subagent_type) : undefined
+  const model = member.model
+    ? {
+        providerID: member.model.providerID,
+        modelID: member.model.modelID,
+      }
+    : undefined
+
+  return {
+    ...(normalizedAgent ? { agent: normalizedAgent } : {}),
+    ...(model ? { model } : {}),
+    ...(member.model?.variant ? { variant: member.model.variant } : {}),
+    ...buildPromptGenerationParams(member.model),
+    parts: [{ type: "text", text }],
+  }
+}

src/features/team-mode/team-runtime/create.test.ts

@@ -1,6 +1,6 @@
 /// <reference types="bun-types" />
 
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test"
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test"
 import { access, mkdtemp, readdir, rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import path from "node:path"
@@ -90,7 +90,7 @@ describe("createTeamRun", () => {
     resolveMemberMock.mockClear()
   })
 
-  afterEach(async () => {
+  afterAll(async () => {
     await Promise.all(temporaryDirectories.splice(0).map(async (directoryPath) => rm(directoryPath, { recursive: true, force: true })))
   })
 
@@ -152,6 +152,9 @@ describe("createTeamRun", () => {
     // then
     expect(firstPrompt).toContain("Do not call lead-only lifecycle tools")
     expect(firstPrompt).not.toContain("3. Request shutdown via `team_shutdown_request`")
+    expect(firstPrompt).toContain("Include `summary` and `references`")
+    expect(firstPrompt).toContain("Move to `status: \"in_progress\"` when you start working")
+    expect(firstPrompt).toContain("delegate-task: Do not call this")
     expect(firstPrompt).toContain("lead can decide whether to request shutdown")
   })
 

src/features/team-mode/team-runtime/create.ts

@@ -13,6 +13,7 @@ import { registerTeamSession } from "../team-session-registry"
 import type { RuntimeState, TeamSpec } from "../types"
 import { activateTeamLayout } from "./activate-team-layout"
 import { cleanupTeamRunResources } from "./cleanup-team-run-resources"
+import { buildTeammateCommunicationAddendum } from "../member-guidance"
 import { resolveMember } from "./resolve-member"
 import { shouldReuseCallerLeadSession } from "../resolve-caller-team-lead"
 import { sweepStaleTeamSessions } from "../team-layout-tmux/sweep-stale-team-sessions"
@@ -94,32 +95,17 @@ async function waitForTaskSessionId(bgMgr: BackgroundManager, task: BackgroundTa
   return sessionId
 }
 
-const TEAMMATE_COMMUNICATION_ADDENDUM = `
-# Team Communication
-
-You are running as a team member. Your text responses are NOT visible to other team members or the lead.
-
-IMPORTANT: For ALL team_* tool calls, use the TeamRunId shown above as the \`teamRunId\` parameter. Do NOT use the team name.
-
-Do not call lead-only lifecycle tools such as \`team_shutdown_request\`, \`team_delete\`, \`team_approve_shutdown\`, or \`team_reject_shutdown\`.
-
-Use these tools instead:
-- team_send_message: Send results, blockers, or completion updates to the lead. Use \`to: "lead"\` for the lead, \`to: "<name>"\` for a specific member.
-- team_task_update: Update your task status. Use \`status: "claimed"\` when starting, \`status: "in_progress"\` while working, \`status: "completed"\` when done.
-- team_task_list: See all team tasks and their status.
-- team_task_get: Get details of a specific task.
-
-When you finish your assigned work, ALWAYS:
-1. Send your results to lead via team_send_message
-2. Mark your task as completed via team_task_update
-3. Send a completion message to lead so the lead can decide whether to request shutdown
-`
-
-function buildMemberPrompt(spec: TeamSpec, member: TeamSpec["members"][number], teamRunId: string, worktreePath?: string): string {
+function buildMemberPrompt(
+  spec: TeamSpec,
+  member: TeamSpec["members"][number],
+  teamRunId: string,
+  config: TeamModeConfig,
+  worktreePath?: string,
+): string {
   const promptLines = [`Team: ${spec.name}`, `TeamRunId: ${teamRunId}`, `Member: ${member.name}`]
   if (worktreePath) promptLines.push(`Worktree: ${worktreePath}`)
   if (member.prompt) promptLines.push(member.prompt)
-  promptLines.push(TEAMMATE_COMMUNICATION_ADDENDUM)
+  promptLines.push(buildTeammateCommunicationAddendum(config))
   return promptLines.join("\n")
 }
 
@@ -202,7 +188,7 @@ export async function createTeamRun(
           const resolvedMember = await resolveMember(member, ctx, categoryExamples, spec.leadAgentId)
           const task = await bgMgr.launch({
             description: `Create team member ${spec.name}/${member.name}`,
-            prompt: buildMemberPrompt(spec, member, runtimeState.teamRunId, resource.worktreePath),
+            prompt: buildMemberPrompt(spec, member, runtimeState.teamRunId, config, resource.worktreePath),
             agent: resolvedMember.agentToUse,
             parentSessionID: leadSessionId,
             parentMessageID: options?.parentMessageID ?? `team-create:${runtimeState.teamRunId}:${member.name}`,

src/features/team-mode/team-runtime/status.test.ts

@@ -100,9 +100,9 @@ describe("aggregateStatus", () => {
     // then
     expect(result.teamName).toBe("team-alpha")
     expect(result.members).toEqual([
-      expect.objectContaining({ name: "lead", unreadMessages: 0 }),
-      expect.objectContaining({ name: "member-1", unreadMessages: 2 }),
-      expect.objectContaining({ name: "member-2", unreadMessages: 0 }),
+      expect.objectContaining({ name: "lead", unreadMessages: 0, delegateTaskCallsUsed: 0, delegateTaskBudgetRemaining: undefined }),
+      expect.objectContaining({ name: "member-1", unreadMessages: 2, delegateTaskCallsUsed: 0, delegateTaskBudgetRemaining: 0 }),
+      expect.objectContaining({ name: "member-2", unreadMessages: 0, delegateTaskCallsUsed: 0, delegateTaskBudgetRemaining: 0 }),
     ])
     expect(result.tasks).toEqual({ pending: 4, claimed: 0, in_progress: 0, completed: 0, deleted: 0, total: 4 })
   })

src/features/team-mode/team-runtime/status.ts

@@ -23,6 +23,8 @@ export interface TeamStatus {
     worktreePath?: string
     unreadMessages: number
     paneId?: string
+    delegateTaskCallsUsed: number
+    delegateTaskBudgetRemaining?: number
   }>
   tasks: {
     pending: number
@@ -141,6 +143,10 @@ export async function aggregateStatus(
       worktreePath: member.worktreePath,
       unreadMessages,
       paneId: member.tmuxPaneId,
+      delegateTaskCallsUsed: member.delegateTaskCallsUsed ?? 0,
+      delegateTaskBudgetRemaining: member.agentType === "leader"
+        ? undefined
+        : Math.max(0, config.member_delegate_task_budget - (member.delegateTaskCallsUsed ?? 0)),
     })),
     tasks: countTasks(tasks),
     shutdownRequests: runtimeState.shutdownRequests,

src/features/team-mode/team-state-store/store.ts

@@ -113,6 +113,7 @@ export async function createRuntimeState(
       status: "pending",
       color: member.color,
       worktreePath: member.worktreePath,
+      delegateTaskCallsUsed: 0,
       lastInjectedTurnMarker: undefined,
       pendingInjectedMessageIds: [],
     })),

src/features/team-mode/tools/messaging.ts

@@ -3,10 +3,8 @@ import { randomUUID } from "node:crypto"
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool"
 
 import type { TeamModeConfig } from "../../../config/schema/team-mode"
-import { stripAgentListSortPrefix } from "../../../shared/agent-display-names"
 import { log } from "../../../shared/logger"
-import { applySessionPromptParams } from "../../../shared/session-prompt-params-helpers"
-import { SessionCategoryRegistry } from "../../../shared/session-category-registry"
+import { applyMemberSessionRouting, buildMemberPromptBody } from "../member-session-routing"
 import { lookupTeamSession } from "../team-session-registry"
 import { loadRuntimeState } from "../team-state-store/store"
 import { buildEnvelope } from "../team-mailbox/poll"
@@ -43,30 +41,6 @@ type TeamRuntimeDetails = {
   activeMembers: string[]
 }
 
-function buildPromptGenerationParams(model: {
-  reasoningEffort?: string
-  temperature?: number
-  top_p?: number
-  maxTokens?: number
-  thinking?: { type: "enabled" | "disabled"; budgetTokens?: number }
-} | undefined): Record<string, unknown> {
-  if (!model) {
-    return {}
-  }
-
-  const promptOptions: Record<string, unknown> = {
-    ...(model.reasoningEffort ? { reasoningEffort: model.reasoningEffort } : {}),
-    ...(model.thinking ? { thinking: model.thinking } : {}),
-  }
-
-  return {
-    ...(model.temperature !== undefined ? { temperature: model.temperature } : {}),
-    ...(model.top_p !== undefined ? { topP: model.top_p } : {}),
-    ...(model.maxTokens !== undefined ? { maxOutputTokens: model.maxTokens } : {}),
-    ...(Object.keys(promptOptions).length > 0 ? { options: promptOptions } : {}),
-  }
-}
-
 async function resolveTeamRuntimeDetails(teamRunId: string, sessionID: string, config: TeamModeConfig): Promise<TeamRuntimeDetails> {
   const registryEntry = lookupTeamSession(sessionID)
   if (registryEntry?.teamRunId === teamRunId) {
@@ -126,7 +100,12 @@ async function deliverLive(
     if (reservation === null) continue
 
     const recipientMember = runtimeState.members.find((entry) => entry.name === recipientName)
-    const recipientSessionId = recipientMember?.sessionId
+    if (!recipientMember) {
+      await releaseDeliveryReservation(reservation).catch(() => {})
+      continue
+    }
+
+    const recipientSessionId = recipientMember.sessionId
     if (!recipientSessionId) {
       log("[team-mailbox] live delivery unavailable, falling back to inbox injection", {
         reason: "missing-session-id",
@@ -147,28 +126,12 @@ async function deliverLive(
       continue
     }
 
-    const recipientAgent = recipientMember?.subagent_type
-    const recipientModel = recipientMember?.model
-      ? { providerID: recipientMember.model.providerID, modelID: recipientMember.model.modelID }
-      : undefined
-    const recipientVariant = recipientMember?.model?.variant
-    const normalizedRecipientAgent = recipientAgent ? stripAgentListSortPrefix(recipientAgent) : undefined
-
-    if (recipientMember?.category) {
-      SessionCategoryRegistry.register(recipientSessionId, recipientMember.category)
-    }
-    applySessionPromptParams(recipientSessionId, recipientMember?.model)
+    applyMemberSessionRouting(recipientSessionId, recipientMember)
 
     try {
       await client.session.promptAsync({
         path: { id: recipientSessionId },
-        body: {
-          ...(normalizedRecipientAgent ? { agent: normalizedRecipientAgent } : {}),
-          ...(recipientModel ? { model: recipientModel } : {}),
-          ...(recipientVariant ? { variant: recipientVariant } : {}),
-          ...buildPromptGenerationParams(recipientMember?.model),
-          parts: [{ type: "text", text: envelope }],
-        },
+        body: buildMemberPromptBody(recipientMember, envelope),
       })
       await commitDeliveryReservation(reservation)
       log("[team-mailbox] live delivery committed", {

src/features/team-mode/tools/query.test.ts

@@ -64,7 +64,7 @@ describe("query tools", () => {
       teamName: "team-alpha",
       status: "active",
       createdAt: 1,
-      members: [],
+      members: [{ name: "worker", unreadMessages: 0, delegateTaskCallsUsed: 0, delegateTaskBudgetRemaining: 0 }],
       tasks: { pending: 0, claimed: 0, in_progress: 0, completed: 0, deleted: 0, total: 0 },
       shutdownRequests: [],
       concurrency: { runningOnSameModel: 0, queuedOnSameModel: 0 },