feat(team-mode): Claude Code Agent Teams parity (OFF by default, 12 team_* tools)

[code-yeongyu]

Summary

Implements Team Mode for omo — Claude Code Agent Teams parity at the OpenCode plugin layer. OFF by default; enabled via JSONC config. Provides parallel multi-agent coordination through 12 team_* tools with role-based access control, deferred-ack mailbox semantics, durable runtime state, optional per-member git worktrees, and optional tmux visualization.

Plan: .sisyphus/plans/team-mode.md (Momus-approved, iteration 7). All 28 implementation tasks delivered across 5 waves + Final Wave Oracle audits.

Highlights

• Config-gated: team_mode.enabled: false by default. Zero impact on existing users.
• Full category + agent support: Members can be either a category routing through sisyphus-junior (kind: "category") or a direct subagent_type (kind: "subagent_type"). Eligible direct agents: sisyphus, atlas, sisyphus-junior, hephaestus. Read-only and orchestration-only agents (oracle, librarian, explore, multimodal-looker, metis, momus, prometheus) are rejected at parse time with verbatim §V.3 messages.
• 12 team_* tools: Lifecycle (team_create/_delete/_shutdown_request/_approve_shutdown/_reject_shutdown), messaging (team_send_message), tasks (team_task_create/_list/_update/_get), query (team_status/_list).
• At-least-once mailbox: poll records pendingInjectedMessageIds in durable RuntimeState; ack happens at session.idle (D-15). Crash before idle → message re-delivered next session.
• Live-delivery reservation: team_send_message writes live-recipient messages directly under .delivering-<id>.json so the transform-hook fallback cannot double-inject the envelope while promptAsync is in flight. Atomic rename to processed/ on success, back to the unread slot on failure, reclaim-on-resume for stranded reservations.
• Single-file 3-line locks per §III.7. Atomic writes via tmp + fsync + rename (D-05).
• Project-scope wins on collision (D-23) with structured warning.
• Optional tmux layout (focus + grid windows). Each pane runs opencode attach against the member session. Failures isolated — never blocks team creation (D-34).
• Doctor check: bunx oh-my-opencode doctor reports team-mode status, dependencies, declared/runtime team counts.

Architecture

src/features/team-mode/
├── types.ts                    # TeamSpec, Member (discriminatedUnion), Message, Task, RuntimeState + parseMember
├── deps.ts                     # tmux + git availability probes
├── team-registry/              # paths, loader, validator (project>user scope)
├── team-state-store/           # locks, store (durable transitions), resume (post-reload recovery + stale reservation reclaim + worker liveness)
├── team-mailbox/               # send (pre-reserve for live), inbox, poll (deferred-ack + dedupe), ack, reservation (atomic rename primitives)
├── team-tasklist/              # store, claim (flock), update, dependencies, get, list (individual JSON files + .highwatermark)
├── team-worktree/              # manager, cleanup (optional git worktree per member)
├── team-runtime/               # create (with rollback), shutdown (2-phase), resolve-member (dual routing), status, resolve-caller-team-lead
├── team-layout-tmux/           # optional focus + grid layout via opencode attach
└── tools/                      # 12 team_* MCP tools

src/hooks/
├── team-mailbox-injector/      # transform-phase, prepends <peer_message ...> envelopes
├── team-tool-gating/           # role-based access (lead vs member vs neither)
└── team-session-events/        # lead-orphan, member-error, idle-wake-hint (with ack-on-idle)

src/cli/doctor/checks/
└── team-mode.ts                # doctor diagnostic

Storage layout

~/.omo/
├── teams/{name}/config.json                      # declared team specs (directory-style, Claude Code parity)
└── runtime/{teamRunId}/
    ├── state.json                                # durable runtime state machine
    ├── inboxes/{member}/{uuid}.json              # per-recipient atomic mailbox files
    ├── inboxes/{member}/.delivering-{uuid}.json  # transient live-delivery reservation (hidden from polls, counted for backpressure)
    ├── inboxes/{member}/processed/               # acked messages
    └── tasks/{id}.json                           # shared task list with .highwatermark counter

Key invariants

Invariant	Why
Spawn path = BackgroundManager.launch() only	Avoids double session creation
Ack deferred to session.idle	At-least-once preservation on crash (D-15)
Lock file = single 3-line plain text at lockPath	§III.7 Claude Code parity
parseMember emits §V.3 verbatim errors	Plan compliance + Momus verification
Skill has NO mcpConfig	Tools register via plugin ToolRegistry instead
team_create blocked for existing participants	Prevents nested teams (D-21)
Member delegate-task budget = 0	Prevents nested delegation (D-13)
<peer_message ...> envelope literal	Untrusted body never escaped/stripped (D-24)
Live recipients get .delivering-* reservation at write time	No visible inbox window between send and live deliver (Oracle R21 round 2)
Reserved files count toward recipient backpressure	Prevents unlimited queuing behind a slow live recipient (Oracle R21 round 3)

Tests

• 4888 tests pass via bun run script/run-ci-tests.ts (full suite with proper isolation).
• Per-module test files for every team-mode source file.
• Integration test scaffold (src/features/team-mode/integration.test.ts) covering C-10 end-to-end scenarios (single-member echo, 2-member task pipeline, resume after restart, parallel bound enforcement).
• bun run typecheck exit 0.

Documentation

• User guide: docs/guide/team-mode.md (refreshed for opencode attach tmux flow + .delivering-* reservation file)
• Module architecture: src/features/team-mode/AGENTS.md
• Doctor check: bunx oh-my-opencode doctor

Reviewer notes

• Branch contains atomic commits per task. Squash on merge if preferred.
• Reference projects consulted: ../free-code (Claude Code experimental Agent Teams) and ../opencode (plugin API + session API).
• All Oracle/Momus iteration findings (P-1 §V.3 messages, P-2 lock format, T12 worktree absence, status.ts gaps, R20 streamer race, R21 runtime bugs) addressed via dedicated fix commits.
• No new npm dependencies added.
• Existing OpenCode tool registry, hook registration, doctor check pipeline reused — minimal core changes.

Out of scope (per Momus iteration 5/6 lock-in)

• No nested teams.
• No synchronous reply waits.
• No agentika integration.
• No Dori/Watcher/Monitor/Escalation extensions.
• No topic-based pub/sub.

Post-implementation verification (Oracle R20 — 2026-04-18)

After Oracle R5–R17 identified and the branch fixed a sequence of race conditions in the team-session-streamer hook (enqueue ordering, drain mutex, scheduler stop/dispose split, generation tokens, pre-mapping state, polling-based retry, etc.), Oracle verified the final code on ed7a816c against a fully interactive terminal QA of the whole lifecycle in one fresh run.

Oracle R20 verdict: VERIFY_PASS.

Evidence: a single fresh opencode run executed the entire lifecycle end-to-end in one continuous transcript: team_create → member spawn → team_status × 2 → team_shutdown_request + team_approve_shutdown for each member → team_delete. Post-delete invariants all passed.

The streamer-based visualization has since been removed (see R21 below); tmux visualization now attaches via opencode attach directly, which required no equivalent streaming gate.

Post-implementation runtime fixes (Oracle R21 — 2026-04-19)

Three full Oracle review rounds identified and fixed live-runtime bugs that persisted after R20. All findings land as atomic TDD commits with regression tests on feat/team-mode between 063e3c53..646344df.

Round 1 — 4 bugs in durable runtime behavior:

1. poll.ts — pendingInjectedMessageIds accumulated duplicates of the same messageId every turn without ack landing (observed 8-12 duplicates per message in production state.json). Dedupe via Array.from(new Set([...])). → 88e9b34c
2. messaging.ts — deliverLive() called promptAsync before ackMessages, so the transform-hook fallback could read the still-unread inbox file and inject the envelope a second time when promptAsync landed. Introduced team-mailbox/reservation.ts with atomic rename-based reservation. → c15c1e00
3. messaging.ts — broadcast activeMembers filtered to members with a live sessionId AND included the sender itself; missed members that hadn't spawned yet and echoed lead broadcasts back into the lead's own inbox. Resolved to all members minus sender. → 737e6eb6
4. resume.ts — resumeAllTeams only verified the lead session; teams with every worker dead but an alive lead stayed active pointing to phantom sessions. Added worker-session inspection with orphan-on-all-dead semantics. → 70ed63f2

Round 2 — 3 follow-up bugs Oracle caught in the R1 fixes:

1. Race still existed between sendMessage writing <id>.json and deliverLive renaming it. Moved reservation to write time via SendContext.reservedRecipients; sendMessage now writes live-recipient messages directly under .delivering-<id>.json. Made reserveMessageForDelivery idempotent (pre-reserved stat OR on-the-fly rename for the rare session-appears-after-send case). → d3c468c8
2. Stranded .delivering-* files were invisible to listUnreadMessages (dotfile filter) and only logged release failures. Added reclaimStaleReservations(teamRunId, memberName, config, ttl), called per member during resume with a 10 minute TTL. → b2180928 + 290e189b
3. inspectWorkerMembers counted every sessionId === undefined worker as alive. After one resume cleared a dead worker's sessionId, a later resume treated it as alive; if the last live worker then died the team stayed active with zero live workers. Fixed by checking member.status === "errored" first. → 65b49bf6

Round 3 — 1 regression Oracle caught in the R2 fixes:

1. The R2-round-1 fix accidentally broke backpressure: getUnreadSizeBytes excluded all dotfiles, so pre-reserved .delivering-*.json messages did not count toward recipient_unread_max_bytes. Concurrent sends could stack arbitrary in-flight traffic behind a slow live recipient. Tightened the filter to include .delivering-*.json while still excluding lock/metadata dotfiles. → 646344df

Oracle R21 final verdict: <promise>LOOKS_GOOD</promise>.

Residual risk documented by Oracle: Same-process orphaned .delivering-* reservations now correctly consume recipient backpressure budget, so a stranded reservation can conservatively block new sends until release or restart-time reclaim (10 min TTL). Acceptable tradeoff versus the pre-fix unlimited-backpressure-bypass bug.

Post-fix verification:

• bun run script/run-ci-tests.ts → 4888 pass / 0 fail
• bun run typecheck → exit 0
• LSP diagnostics clean on all touched files (poll.ts, send.ts, reservation.ts, messaging.ts, resume.ts)
• User guide refreshed for the new reservation mechanic and opencode attach tmux flow → 052d1d1e

---

Summary by cubic

Adds Team Mode for parallel multi-agent coordination with 12 team_* tools, durable state, a shared mailbox with live‑delivery reservations, and an optional tmux layout that streams each member via opencode attach. Off by default; enable with team_mode.enabled to surface the team-mode skill and a new doctor check.

• New Features

  • Root team_mode config and JSON schema (bounds, defaults); doctor check validates config, dirs, and tmux/git; builtin team-mode skill is config‑gated.
  • Durable runtime with resume-on-reload (resume deferred post-init to avoid startup deadlock); lead defaults to the calling agent and reuses the caller session.
  • Shared task list with file‑locked claims; mailbox has deferred-ack and live-delivery reservations via .delivering-*.json to prevent double‑inject; pending IDs deduped; reservations count toward backpressure and are reclaimed on resume.
  • Broadcast excludes sender and queues for not‑yet‑spawned members.
  • Optional tmux visualization creates focus + grid panes per member via opencode attach; helpers close panes, rebalance windows, and sweep stale omo-team-* sessions.
  • Team Mode guide added and linked from the docs.

• Refactors

  • Replaced custom FIFO streamer with opencode attach; tmux runner hardened with retry/timeout and safer attach command.
  • Background manager treats session.error as transient if the session still exists.
  • Plugin loader recovers stale install paths and legacy plugin.json, with strict manifest name matching and deterministic version selection.
  • CI isolates new team-mode tests; .sisyphus/ fully ignored.

^{Written for commit d2f03ac. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 189 files

Confidence score: 3/5

• There is a concrete user-facing behavior risk in src/cli/doctor/checks/index.ts: registering Team Mode causes doctor to run ensureBaseDirs(), which can create or re-permission ~/.omo during what should be a read-only health check.
• This keeps merge risk in the moderate range because the issue is medium severity (5/10) with high confidence, while the docs issue in docs/guide/team-mode.md is low severity and mainly affects copy-paste success (subagent_type: explore fails validation).
• Pay close attention to src/cli/doctor/checks/index.ts and docs/guide/team-mode.md - prevent side effects in doctor and fix the invalid Team Mode example so guidance matches parser rules.

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed. cubic prioritises the most important files to review.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/guide/team-mode.md">

<violation number="1" location="docs/guide/team-mode.md:45">
P3: The example uses an ineligible `subagent_type` (`explore`), so copying the guide will fail parse-time validation.</violation>
</file>

<file name="src/cli/doctor/checks/index.ts">

<violation number="1" location="src/cli/doctor/checks/index.ts:39">
P2: Registering Team Mode here makes `doctor` perform filesystem writes via `ensureBaseDirs()`. Health checks should stay read-only, or diagnostics can unexpectedly create/re-permission `~/.omo` directories just by running the command.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Registering Team Mode here makes doctor perform filesystem writes via ensureBaseDirs(). Health checks should stay read-only, or diagnostics can unexpectedly create/re-permission ~/.omo directories just by running the command.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/cli/doctor/checks/index.ts, line 39:

<comment>Registering Team Mode here makes `doctor` perform filesystem writes via `ensureBaseDirs()`. Health checks should stay read-only, or diagnostics can unexpectedly create/re-permission `~/.omo` directories just by running the command.</comment>

<file context>
@@ -32,5 +33,10 @@ export function getAllCheckDefinitions(): CheckDefinition[] {
+    {
+      id: CHECK_IDS.TEAM_MODE,
+      name: CHECK_NAMES[CHECK_IDS.TEAM_MODE],
+      check: checkTeamMode,
+    },
   ]
</file context>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.}

[cubic-dev-ai]

1 issue found across 76 files (changes from recent commits).

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed. cubic prioritises the most important files to review.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".gitignore">

<violation number="1" location=".gitignore:2">
P2: Ignoring the whole `.sisyphus/` tree removes the prior allowlist for `.sisyphus/rules/`, so rule files there can no longer be versioned normally.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

4 issues found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/hooks/team-tool-gating/hook.ts">

<violation number="1" location="src/hooks/team-tool-gating/hook.ts:131">
P2: `team_list` is returned too late: it still re-loads participant state first, so a bad runtime can make this public tool fail before the allow-list branch runs.</violation>
</file>

<file name="src/plugin/event.ts">

<violation number="1" location="src/plugin/event.ts:285">
P2: Do not gate the idle wake hint on `promptAsync`; it also performs ack/cleanup work that should still run when promptAsync is unavailable.</violation>
</file>

<file name="src/features/team-mode/team-registry/loader.ts">

<violation number="1" location="src/features/team-mode/team-registry/loader.ts:125">
P2: Validating the normalized spec can produce member error paths that no longer match the authored JSON.</violation>
</file>

<file name="src/features/team-mode/team-registry/team-spec-input-normalizer.ts">

<violation number="1" location="src/features/team-mode/team-registry/team-spec-input-normalizer.ts:44">
P2: A top-level `lead` can be silently ignored when another member already uses the same name, so `leadAgentId` may point at the wrong member definition.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

13 issues found across 30 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin/event.ts">

<violation number="1" location="src/plugin/event.ts:275">
P2: `teamSessionStreamer` is executed twice for the same event, which can duplicate FIFO writes and tmux visualization updates.</violation>
</file>

<file name="src/hooks/team-session-streamer/fifo-writer.ts">

<violation number="1" location="src/hooks/team-session-streamer/fifo-writer.ts:9">
P1: Non-blocking FIFO writes can be partial, but this helper does a single write and ignores `bytesWritten`, so trailing data may be lost.</violation>
</file>

<file name="src/hooks/team-session-streamer/hook.ts">

<violation number="1" location="src/hooks/team-session-streamer/hook.ts:97">
P2: Advancing the per-part cursor before confirming a stream target can drop early text when team resolution is temporarily unavailable.</violation>

<violation number="2" location="src/hooks/team-session-streamer/hook.ts:183">
P2: Handle `message.part.delta` here as well; the current guard drops incremental text events, so tmux streaming can miss live output.</violation>
</file>

<file name="src/features/team-mode/tools/lifecycle-test-fixture.ts">

<violation number="1" location="src/features/team-mode/tools/lifecycle-test-fixture.ts:109">
P2: Deleting a team leaves the `teamRuns` reverse index stale, so recreating the same team/lead pair later can throw `missing runtime` instead of creating a fresh run.</violation>

<violation number="2" location="src/features/team-mode/tools/lifecycle-test-fixture.ts:120">
P2: Mock approval does not require an existing shutdown request, so lifecycle tests can miss invalid approve-before-request sequencing.</violation>
</file>

<file name="src/features/team-mode/team-layout-tmux/layout.ts">

<violation number="1" location="src/features/team-mode/team-layout-tmux/layout.ts:102">
P1: The same member FIFO is attached to both tmux windows, so focus and grid panes will race to consume output and each view can miss chunks of the stream.</violation>
</file>

<file name="src/features/team-mode/team-runtime/delete-team.ts">

<violation number="1" location="src/features/team-mode/team-runtime/delete-team.ts:26">
P1: Member deletability is checked on a stale snapshot before the locked state transition, so a concurrent state update can make a member active again and still have this deletion path remove its worktree/runtime artifacts.</violation>

<violation number="2" location="src/features/team-mode/team-runtime/delete-team.ts:45">
P1: Use the lead session ID when cancelling team background tasks; using `teamRunId` leaves member tasks running after deletion.</violation>
</file>

<file name="src/features/team-mode/team-runtime/activate-team-layout.ts">

<violation number="1" location="src/features/team-mode/team-runtime/activate-team-layout.ts:29">
P2: Clean up the tmux layout if persisting `tmuxPaneId` fails; otherwise a state-store error during team creation leaks the new tmux session.</violation>
</file>

<file name="src/features/team-mode/tools/lifecycle.test.ts">

<violation number="1" location="src/features/team-mode/tools/lifecycle.test.ts:101">
P2: Await the `rejects` assertion so the test actually verifies the promise rejection.</violation>
</file>

<file name="src/features/team-mode/team-runtime/cleanup-team-run-resources.ts">

<violation number="1" location="src/features/team-mode/team-runtime/cleanup-team-run-resources.ts:58">
P2: Rollback leaves tmux layout resources behind if layout activation fails partway through, and it never removes the layout FIFO directory.</violation>
</file>

<file name="src/features/team-mode/team-runtime/create.ts">

<violation number="1" location="src/features/team-mode/team-runtime/create.ts:168">
P2: Mark the layout as created before awaiting `activateTeamLayout()`. Otherwise a post-create failure can skip tmux cleanup and leave the session running.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/team-mode/team-runtime/delete-team-bg-cancel.test.ts">

<violation number="1" location="src/features/team-mode/team-runtime/delete-team-bg-cancel.test.ts:80">
P2: This test never creates the absent-`leadSessionId` state it claims to cover, so it does not validate the no-cancellation branch.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 14 unresolved issues from previous reviews.}

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

_{Requires human review: Auto-approval blocked by 13 unresolved issues from previous reviews.}

[cubic-dev-ai]

You're iterating quickly on this pull request. To help protect your rate limits, cubic has paused automatic reviews on new pushes for now—when you're ready for another review, comment @cubic-dev-ai review.