english/.opencode/skills/team/references/agent-teams-controls-and-modes.md

Agent Teams -- Controls, Display Modes & Task Management

Source: https://code.claude.com/docs/en/agent-teams Version captured: Claude Code v2.1.80 (March 2026)

Display Modes

• In-process (default fallback): all teammates in one terminal. Shift+Up/Down to navigate. Works in any terminal.
• Split panes: each teammate gets own pane. Requires tmux or iTerm2.

Default is "auto" -- uses split panes if already inside a tmux session, otherwise in-process. The "tmux" setting enables split-pane mode and auto-detects tmux vs iTerm2.

{ "teammateMode": "in-process" }

Per-session override: claude --teammate-mode in-process

Split panes NOT supported in: VS Code terminal, Windows Terminal, Ghostty.

tmux setup: install via system package manager. iTerm2 setup: install it2 CLI, enable Python API in iTerm2 > Settings > General > Magic.

Model Requirements

All Agent Team teammates must run Opus 4.6 -- this is a hard constraint. Mixed-model teams (e.g., Sonnet for devs, Haiku for testers) are NOT supported within Agent Teams.

For mixed-model workflows, use subagents instead (the Agent tool supports model: "haiku" | "sonnet" | "opus" per spawn).

Plan Approval

Require teammates to plan before implementing:

Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.

Flow:

1. Teammate works in read-only plan mode
2. Teammate finishes planning -> sends plan_approval_request to lead
3. Lead reviews -> approves via SendMessage(type: "plan_approval_response", approve: true)
4. If rejected: teammate stays in plan mode, revises based on feedback, resubmits
5. Once approved: teammate exits plan mode, begins implementation

Influence criteria: "only approve plans that include test coverage" or "reject plans that modify the database schema"

Delegate Mode

Restricts lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. No code editing.

Useful when lead should focus entirely on orchestration -- breaking down work, assigning tasks, synthesizing results.

Enable: Press Shift+Tab after team creation to cycle into delegate mode.

Direct Teammate Interaction

• In-process: Shift+Up/Down select teammate, type to message. Enter view session. Escape interrupt current turn. Ctrl+T toggle task list.
• Split panes: click into pane to interact directly. Each teammate has full terminal view.

Task Assignment & Claiming

Three states: pending -> in_progress -> completed. Tasks can have dependencies -- blocked until dependencies resolve.

• Lead assigns: tell lead which task -> which teammate
• Self-claim: after finishing, teammate picks next unassigned, unblocked task automatically
• Auto-unblock: completing a blocking task automatically unblocks dependents

File locking prevents race conditions on simultaneous claiming.

Worktree Isolation for Implementation

When spawning developer teammates, use isolation: "worktree" on the Agent tool:

Agent(
  subagent_type: "fullstack-developer",
  model: "opus",
  isolation: "worktree",
  run_in_background: true,
  prompt: "Implement auth module..."
)

Each dev gets own worktree + branch. No file conflicts during parallel work. Lead merges branches after all devs complete.

When to use: Always for cook/implementation templates. Not needed for research/review (read-only).

Background Spawning

Use run_in_background: true on the Agent tool to spawn teammates non-blocking:

• Lead continues orchestration while teammates work
• Automatic notification when teammate completes
• No polling needed -- TaskCompleted hook fires on completion
• Use TaskList as fallback if no events in 60s

Shutdown

Ask the researcher teammate to shut down

Teammate can approve (exit) or reject with explanation. Teammates finish current request/tool call before shutting down -- can be slow.

Cleanup

After all teammates shut down, call TeamDelete (no parameters). Fails if active teammates still exist.

Removes shared team resources (~/.opencode/teams/ and ~/.opencode/tasks/ entries).

Hook-Based Orchestration

Event-Driven Monitoring

Instead of polling TaskList, lead receives automatic context injection:

• TaskCompleted -- fires when any teammate completes a task. Lead gets progress counts.
• TeammateIdle -- fires when teammate turn ends. Lead gets available task info.

Recommended Pattern

1. Lead creates tasks and spawns teammates (with run_in_background: true)
2. TaskCompleted hook notifies lead as tasks finish (progress: N/M)
3. TeammateIdle hook suggests reassignment or shutdown
4. Lead acts on suggestions (spawn tester, shut down, reassign)
5. Fallback: Check TaskList manually if no events received in 60s

This replaces the "poll TaskList every 30s" pattern with reactive orchestration.