oh-my-opencode 4.16.1 → 4.16.3

package/packages/omo-codex/plugin/components/teammode/skills/teammode/scripts/team-guide.mjs

@@ -1,23 +1,57 @@
 // team-guide.mjs - render the member-facing field manual (guide.md) and the short
-// bootstrap trigger a new thread reads on startup. Pure string builders, no I/O.
+// bootstrap trigger a new member reads on startup. Pure string builders, no I/O.
 //
 // The manual is the durable, two-channel replacement for per-prompt guidance: the leader
-// writes it once at team creation, and every member thread is told to READ it instead of
-// receiving the rules inline each turn.
+// writes it once at team creation, and every member is told to READ it instead of
+// receiving the rules inline each turn. Every rendered surface branches on the team's
+// transport: multi_agent_v2 members are native agents addressed by agent path; codex_app
+// members are app threads addressed by thread id.
+
+import { isMultiAgentV2, LEADER_AGENT_PATH } from "./team-transport.mjs";
 
 export function codexThreadLink(threadId) {
 	return `codex://threads/${threadId}`;
 }
 
-function memberLine(member) {
+function transportLabel(team) {
+	return isMultiAgentV2(team)
+		? "MultiAgentV2 (native agents: flat `spawn_agent` / `send_message` / `followup_task`)"
+		: "Codex App threads (`codex_app.*` tools)";
+}
+
+function memberEndpoint(member, v2) {
+	if (v2) {
+		return member.agentPath ? ` | task \`${member.taskName}\` | agent \`${member.agentPath}\`` : " | agent not spawned yet";
+	}
 	const thread = member.threadId ? ` | thread ${member.threadId} (${codexThreadLink(member.threadId)})` : " | thread not created yet";
+	const title = member.threadTitle ? ` | thread title \`${member.threadTitle}\`` : "";
+	return `${title}${thread}`;
+}
+
+function memberLine(member, v2) {
 	const wt = member.worktree?.path ? ` | worktree ${member.worktree.path}` : "";
 	const name = member.name ? ` "${member.name}"` : "";
-	const title = member.threadTitle ? ` | thread title \`${member.threadTitle}\`` : "";
-	return `- **${member.id}**${name} (${member.lens}) - ${member.focus}${member.deliverable ? ` -> ${member.deliverable}` : ""}${title}${thread}${wt} [${member.status}]`;
+	return `- **${member.id}**${name} (${member.lens}) - ${member.focus}${member.deliverable ? ` -> ${member.deliverable}` : ""}${memberEndpoint(member, v2)}${wt} [${member.status}]`;
+}
+
+function worktreeMemberEndpoint(member, v2) {
+	if (v2) return member.agentPath ? `; agent \`${member.agentPath}\`` : "";
+	return member.threadId ? `; thread ${codexThreadLink(member.threadId)}` : "";
+}
+
+function worktreeReadinessNote(v2) {
+	if (v2) {
+		return `Your worktree is created by the leader BEFORE you spawn; the exact path is in your row
+above and in your bootstrap. If the leader enables isolation mid-run, the new path arrives
+as a \`followup_task\` - switch to it before your next edit.`;
+	}
+	return `If Codex returns only \`pendingWorktreeId\` while the leader is creating a worktree-backed member
+thread, the thread is not ready yet. The leader must wait until Codex surfaces a real thread id,
+then bind that real id and send the bootstrap.`;
 }
 
 function worktreeSection(team) {
+	const v2 = isMultiAgentV2(team);
 	if (!team.worktree?.enabled) {
 		return `## Worktrees
 
@@ -28,8 +62,8 @@ that is a coordination signal: mark yourself \`blocked\` and tell the leader at
 	const lines = team.members
 		.filter((m) => m.worktree?.path || m.worktree?.branch)
 		.map((m) => {
-			const thread = m.threadId ? `; thread ${codexThreadLink(m.threadId)}` : "";
-			return `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\`${thread}`;
+			const bindHint = v2 ? "(assign with bind-agent --cwd)" : "(assign with bind-thread --cwd)";
+			return `- **${m.id}**: worktree \`${m.worktree.path ?? bindHint}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\`${worktreeMemberEndpoint(m, v2)}`;
 		});
 	return `## Worktrees (ISOLATION IS ON - this is not optional for you)
 
@@ -41,25 +75,48 @@ Before editing, verify that your assigned worktree exists and contains repo file
 missing, empty, or does not look like a git worktree/repository yet, send \`BLOCKED: worktree not ready\`
 to the leader and wait instead of editing any parent checkout or empty directory.
 
-If Codex returns only \`pendingWorktreeId\` while the leader is creating a worktree-backed member
-thread, the thread is not ready yet. The leader must wait until Codex surfaces a real thread id,
-then bind that real id and send the bootstrap.
+${worktreeReadinessNote(v2)}
 
-${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
+${lines.length ? lines.join("\n") : "- (worktree paths are assigned as members are bound; read team.json for yours)"}`;
+}
+
+function addressBookRules(team) {
+	if (isMultiAgentV2(team)) {
+		return `- **Reach the leader and your peers with \`send_message\` - not by narrating in your own
+  transcript, where no one reads it.** The address book is in team.json: the leader's target
+  is \`${LEADER_AGENT_PATH}\`, and each peer's target is its \`members[].agentPath\` (built from its
+  \`members[].taskName\`).
+- **Use \`send_message\` for updates and \`followup_task\` only when handing a peer a NEW task**
+  that should wake it. Never invent an agent path - read it from team.json.`;
+	}
+	return `- **Reach the leader and your peers with \`codex_app.send_message_to_thread\` - not by narrating in
+  your own thread, where no one reads it.** The address book is in team.json: the leader thread id
+  is \`leader.sessionId\`, and each peer thread id is its \`members[].threadId\`.
+- **When you mention a Codex thread, include its app link too:** \`codex://threads/<threadId>\`.
+  These links are the fastest way for the leader to reopen worktree-backed member threads.`;
+}
+
+function identityHeaderLine(team) {
+	if (isMultiAgentV2(team)) {
+		return `- Member identity convention: each member is the agent path \`${LEADER_AGENT_PATH}/<task name>\` - your row below shows yours; two members never share a task name`;
+	}
+	return `- Thread title convention: \`${team.threadTitleConvention}\` - each member's thread takes its OWN title from its name (your row below shows yours); two members never share a title`;
 }
 
 export function buildGuide(team) {
+	const v2 = isMultiAgentV2(team);
 	const artifacts = team.paths?.artifacts ?? ".omo/teams/<session_id>/artifacts";
 	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
-	const roster = team.members.length ? team.members.map(memberLine).join("\n") : "- (no members yet)";
+	const roster = team.members.length ? team.members.map((member) => memberLine(member, v2)).join("\n") : "- (no members yet)";
 	return `# Team ${team.teamName} - Member Field Manual
 
 > Auto-generated by the teammode script. This file is the single source of truth for how
 > this team works. Re-read it whenever you are unsure - do not improvise the protocol.
 
 - Team: **${team.teamName}** (id \`${team.teamId}\`)
+- Transport: **${transportLabel(team)}**
 - Team state: \`${teamJson}\`
-- Thread title convention: \`${team.threadTitleConvention}\` - each member's thread takes its OWN title from its name (your row below shows yours); two members never share a title
+${identityHeaderLine(team)}
 
 ## Who you are (your identity is fixed)
 
@@ -82,11 +139,7 @@ coordinate with each other, but the leader owns the final decision and integrati
   is mandatory regardless of the language the task was given in.
 - **Exception: when the END USER addresses you directly, reply in the user's own language.**
   Team-internal traffic stays English; user-facing replies match the user.
-- **Reach the leader and your peers with \`codex_app.send_message_to_thread\` - not by narrating in
-  your own thread, where no one reads it.** The address book is in team.json: the leader thread id
-  is \`leader.sessionId\`, and each peer thread id is its \`members[].threadId\`.
-- **When you mention a Codex thread, include its app link too:** \`codex://threads/<threadId>\`.
-  These links are the fastest way for the leader to reopen worktree-backed member threads.
+${addressBookRules(team)}
 - **Push a short message at each of these moments - never batch them into one report at the end:**
   - to the **leader**: every finding or decision, every file or sub-task you finish, a
     \`WORKING: <focus> - <phase>\` heartbeat every few tool calls so you never look stale, a
@@ -116,6 +169,25 @@ Your slice is done only when (1) the deliverable exists, (2) you have evidence i
 (3) you have reported it to the leader. Until all three are true, keep going.`;
 }
 
+function memberIdentityLine(team, member) {
+	if (isMultiAgentV2(team)) {
+		return `Your task name is \`${member.taskName}\` (agent path \`${member.agentPath}\`).`;
+	}
+	return `Your thread title is \`${member.threadTitle}\`.`;
+}
+
+function memberEndpointNote(team, member) {
+	if (isMultiAgentV2(team)) return "";
+	return member.threadId ? `\nYour Codex thread link is ${codexThreadLink(member.threadId)}. Include it when reporting handoffs or worktree status.` : "";
+}
+
+function pushInstruction(team) {
+	if (isMultiAgentV2(team)) {
+		return `Push updates to the leader (target \`${LEADER_AGENT_PATH}\`) and relevant peers (their team.json \`members[].agentPath\`) with \`send_message\` as you work`;
+	}
+	return "Push updates to the leader and relevant peers with `codex_app.send_message_to_thread` as you work";
+}
+
 export function buildMemberPrompt(team, id) {
 	const member = team.members.find((m) => m.id === id);
 	if (!member) throw new Error(`no member with id "${id}"`);
@@ -126,14 +198,13 @@ export function buildMemberPrompt(team, id) {
 		: team.worktree?.enabled
 			? "Wait for the leader to bind your worktree cwd before editing."
 			: "Work from the repository root unless your manual assigns a worktree.";
-	const threadLink = member.threadId ? `\nYour Codex thread link is ${codexThreadLink(member.threadId)}. Include it when reporting handoffs or worktree status.` : "";
 	const readiness =
 		team.worktree?.enabled
 			? "\nBefore editing, verify that your assigned worktree exists and contains repo files. If this prompt arrived before your Codex worktree checkout is ready, or the path is missing, empty, or not a git worktree/repository yet, report `BLOCKED: worktree not ready` to the leader and wait."
 			: "";
-	return `You are member ${member.id}${member.name ? ` (${member.name})` : ""} of team ${team.teamName} - owner of: ${member.focus}. Your thread title is \`${member.threadTitle}\`.
+	return `You are member ${member.id}${member.name ? ` (${member.name})` : ""} of team ${team.teamName} - owner of: ${member.focus}. ${memberIdentityLine(team, member)}
 FIRST read your field manual at \`${guide}\`, then the team state at \`${teamJson}\`; they define your scope, deliverable, the leader, the artifacts directory, and the communication rules.
-${where}${threadLink}${readiness}
+${where}${memberEndpointNote(team, member)}${readiness}
 Communicate with the team and leader in English; reply to the end user in the user's own language.
-Start now. Push updates to the leader and relevant peers with \`codex_app.send_message_to_thread\` as you work - findings, \`WORKING:\` heartbeats, and \`BLOCKED:\` the instant you stall - never just one report at the end.`;
+Start now. ${pushInstruction(team)} - findings, \`WORKING:\` heartbeats, and \`BLOCKED:\` the instant you stall - never just one report at the end.`;
 }

package/packages/omo-codex/plugin/components/teammode/skills/teammode/scripts/team-state.mjs

@@ -13,6 +13,16 @@ import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 
+import {
+	agentPathForTaskName,
+	assertTransport,
+	isMultiAgentV2,
+	LEADER_AGENT_PATH,
+	parseTaskName,
+	parseTeamTransport,
+	TEAM_SCHEMA_VERSION,
+} from "./team-transport.mjs";
+
 export const LENSES = ["area", "ownership", "perspective"];
 export const MEMBER_STATUSES = ["pending", "active", "reported", "blocked", "archived"];
 // A team is never a single member: two or more distinct slices is the minimum. One isolated
@@ -32,22 +42,25 @@ function isoNow(now) {
 	return now ?? new Date().toISOString();
 }
 
-export function buildTeam({ teamName, sessionName, sessionId = null, dir = null, worktreeEnabled = false, baseBranch = "dev", now }) {
+export function buildTeam({ teamName, sessionName, sessionId = null, dir = null, worktreeEnabled = false, baseBranch = "dev", transport, now }) {
 	if (!teamName?.trim()) throw new Error("team name is required");
 	if (!sessionName?.trim()) throw new Error("session name is required");
+	const teamTransport = parseTeamTransport(transport);
+	const v2 = teamTransport === "multi_agent_v2";
 	const ts = isoNow(now);
 	return {
-		schemaVersion: 2,
+		schemaVersion: TEAM_SCHEMA_VERSION,
+		transport: teamTransport,
 		teamId: randomUUID(),
 		teamName: teamName.trim(),
 		sessionName: sessionName.trim(),
 		sessionId,
-		threadTitleConvention: `[${teamName.trim()}] <member name>`,
+		threadTitleConvention: v2 ? null : `[${teamName.trim()}] <member name>`,
 		status: "active",
 		createdAt: ts,
 		updatedAt: ts,
 		archivedAt: null,
-		leader: { kind: "main-session", sessionId },
+		leader: { kind: "main-session", sessionId: v2 ? null : sessionId, agentPath: v2 ? LEADER_AGENT_PATH : null },
 		communication: { memberLanguage: "english", replyToUserInUserLanguage: true },
 		worktree: { enabled: Boolean(worktreeEnabled), baseBranch, root: dir ? join(dir, "worktrees") : null },
 		paths: dir
@@ -124,21 +137,44 @@ function assertUniqueMemberThreadTitle(team) {
 	}
 }
 
-function assertTeamReadyForThreadBinding(team) {
+function assertUniqueMemberTaskName(team) {
+	const seen = new Map();
+	for (const member of team.members) {
+		const taskName = parseTaskName(member.taskName);
+		const previous = seen.get(taskName);
+		if (previous) {
+			throw new Error(`member taskName "${taskName}" duplicates "${previous.taskName}" (no two members may share an agent path)`);
+		}
+		if (member.agentPath !== agentPathForTaskName(taskName)) {
+			throw new Error(`member "${member.id}" agentPath "${member.agentPath}" does not match task name "${taskName}"`);
+		}
+		seen.set(taskName, member);
+	}
+}
+
+function assertUniqueTransportIdentity(team) {
+	if (isMultiAgentV2(team)) assertUniqueMemberTaskName(team);
+	else assertUniqueMemberThreadTitle(team);
+}
+
+function assertTeamReadyForBinding(team) {
 	if (isUnderstaffed(team)) {
 		throw new Error(
-			`cannot bind member threads until the team has at least ${MIN_MEMBERS} distinct members; current count is ${team.members.length}`,
+			`cannot bind members until the team has at least ${MIN_MEMBERS} distinct members; current count is ${team.members.length}`,
 		);
 	}
 	assertUniqueMemberFocus(team);
 	assertUniqueMemberName(team);
-	assertUniqueMemberThreadTitle(team);
+	assertUniqueTransportIdentity(team);
 }
 
-export function addMember(team, { id, focus, lens, deliverable = "", branch = null, name = null }) {
+export function addMember(team, { id, focus, lens, deliverable = "", branch = null, name = null, taskName = null }) {
 	if (!id?.trim()) throw new Error("member id is required");
 	if (!focus?.trim()) throw new Error("member focus is required - a concrete part, ownership area, or perspective");
 	if (!LENSES.includes(lens)) throw new Error(`invalid lens "${lens}" - use one of: ${LENSES.join(", ")}`);
+	const v2 = isMultiAgentV2(team);
+	if (!v2 && taskName !== null) throw new Error("--task-name is only valid on multi_agent_v2 teams");
+	const memberTaskName = v2 ? parseTaskName(taskName) : null;
 	const memberId = id.trim();
 	const memberFocus = focus.trim();
 	// The member name is the short role label that titles this member's thread. Fall back to the
@@ -151,14 +187,20 @@ export function addMember(team, { id, focus, lens, deliverable = "", branch = nu
 	if (duplicateName) {
 		throw new Error(`member name "${memberName}" duplicates "${duplicateName.name ?? duplicateName.focus}" (no two members may produce the same thread title)`);
 	}
+	if (v2) {
+		const duplicateTask = team.members.find((m) => m.taskName === memberTaskName);
+		if (duplicateTask) throw new Error(`member taskName "${memberTaskName}" duplicates "${duplicateTask.taskName}" (no two members may share an agent path)`);
+	}
 	team.members.push({
 		id: memberId,
 		name: memberName,
 		focus: memberFocus,
 		lens,
 		deliverable: deliverable.trim(),
+		taskName: memberTaskName,
+		agentPath: v2 ? agentPathForTaskName(memberTaskName) : null,
 		threadId: null,
-		threadTitle: `[${team.teamName}] ${memberName}`,
+		threadTitle: v2 ? null : `[${team.teamName}] ${memberName}`,
 		cwd: null,
 		worktree: { path: null, branch: branch ?? null },
 		status: "pending",
@@ -167,8 +209,9 @@ export function addMember(team, { id, focus, lens, deliverable = "", branch = nu
 }
 
 export function bindThread(team, { id, threadId, cwd = null, worktreePath = null }) {
+	assertTransport(team, "codex_app", "bind-thread");
 	if (!threadId?.trim()) throw new Error("thread id is required");
-	assertTeamReadyForThreadBinding(team);
+	assertTeamReadyForBinding(team);
 	const m = memberById(team, id);
 	m.threadId = threadId.trim();
 	m.status = "active";
@@ -177,6 +220,21 @@ export function bindThread(team, { id, threadId, cwd = null, worktreePath = null
 	return touch(team, "bind-thread", `member ${id} -> thread ${threadId.trim()}`);
 }
 
+export function bindAgent(team, { id, agentPath, cwd = null, worktreePath = null }) {
+	assertTransport(team, "multi_agent_v2", "bind-agent");
+	if (!agentPath?.trim()) throw new Error("agent path is required");
+	assertTeamReadyForBinding(team);
+	const m = memberById(team, id);
+	const boundPath = agentPath.trim();
+	if (boundPath !== m.agentPath) {
+		throw new Error(`agent path mismatch for member ${m.id}: expected "${m.agentPath}" (task name "${m.taskName}"), got "${boundPath}"`);
+	}
+	m.status = "active";
+	if (cwd) m.cwd = cwd;
+	if (team.worktree.enabled) m.worktree.path = worktreePath ?? cwd ?? m.worktree.path;
+	return touch(team, "bind-agent", `member ${id} -> agent ${boundPath}`);
+}
+
 export function setMemberStatus(team, { id, status, note = "" }) {
 	if (!MEMBER_STATUSES.includes(status)) throw new Error(`invalid status "${status}" - use one of: ${MEMBER_STATUSES.join(", ")}`);
 	memberById(team, id).status = status;
@@ -204,22 +262,44 @@ export function clearMemberWorktree(team, { id }) {
 export function archive(team, { id = null, note = "" } = {}) {
 	if (id) {
 		memberById(team, id).status = "archived";
-		return touch(team, "archive-member", `member ${id}${note ? `: ${note}` : ""}`);
+		const memberQualifier = isMultiAgentV2(team) ? " (team state only; V2 exposes no runtime archive operation)" : "";
+		return touch(team, "archive-member", `member ${id}${memberQualifier}${note ? `: ${note}` : ""}`);
 	}
 	for (const m of team.members) m.status = "archived";
 	team.status = "archived";
 	team.archivedAt = isoNow();
-	return touch(team, "archive", note || "team archived; all members closed");
+	// The default detail must never claim a runtime closure that did not happen: V2 exposes no
+	// runtime archive operation, so only the durable team state is archived there.
+	const defaultDetail = isMultiAgentV2(team)
+		? "team archived; V2 exposes no runtime archive operation - durable team state is the archive"
+		: "team archived; all members closed";
+	return touch(team, "archive", note || defaultDetail);
+}
+
+// schemaVersion 2 predates transports; that skill allowed ONLY Codex App threads as members,
+// so a legacy team is migrated in memory as codex_app and persisted on the next mutation.
+function migrateLegacyTeam(team) {
+	if (team?.schemaVersion !== 2) return team;
+	team.schemaVersion = TEAM_SCHEMA_VERSION;
+	team.transport = "codex_app";
+	if (team.leader && typeof team.leader === "object") team.leader.agentPath = null;
+	for (const member of team.members ?? []) {
+		member.taskName = null;
+		member.agentPath = null;
+	}
+	return team;
 }
 
 export function validateTeam(team) {
-	if (team?.schemaVersion !== 2) throw new Error("invalid team: schemaVersion must be 2");
+	migrateLegacyTeam(team);
+	if (team?.schemaVersion !== TEAM_SCHEMA_VERSION) throw new Error(`invalid team: schemaVersion must be ${TEAM_SCHEMA_VERSION}`);
+	parseTeamTransport(team.transport);
 	if (!team.teamId || !team.teamName) throw new Error("invalid team: teamId and teamName are required");
 	if (team.leader?.kind !== "main-session") throw new Error("invalid team: leader.kind must be main-session");
 	if (!Array.isArray(team.members)) throw new Error("invalid team: members must be an array");
 	assertUniqueMemberFocus(team);
 	assertUniqueMemberName(team);
-	assertUniqueMemberThreadTitle(team);
+	assertUniqueTransportIdentity(team);
 	return team;
 }
 

package/packages/omo-codex/plugin/components/teammode/skills/teammode/scripts/team-transport.mjs

@@ -0,0 +1,55 @@
+// team-transport.mjs - the single source of transport identity for teammode state.
+//
+// A team runs on exactly ONE transport, chosen at init and immutable afterwards:
+// - "multi_agent_v2": members are native Codex MultiAgentV2 agents addressed by task
+//   name / canonical agent path (`/root/<task_name>`), messaged with flat `send_message`
+//   and `followup_task`.
+// - "codex_app": members are durable Codex App threads addressed by thread id, messaged
+//   with `codex_app.send_message_to_thread` (the fallback when flat V2 tools are absent).
+//
+// Zero external dependencies (node builtins only), same portability contract as the
+// sibling scripts.
+
+export const TEAM_SCHEMA_VERSION = 3;
+export const TEAM_TRANSPORTS = ["multi_agent_v2", "codex_app"];
+export const DEFAULT_TEAM_TRANSPORT = "codex_app";
+export const LEADER_AGENT_PATH = "/root";
+
+// Codex validates V2 task names as lowercase letters, digits, and underscores; "root" is
+// the leader's own path segment and can never name a member.
+const TASK_NAME_PATTERN = /^[a-z0-9_]+$/;
+
+export function parseTeamTransport(value = DEFAULT_TEAM_TRANSPORT) {
+	if (!TEAM_TRANSPORTS.includes(value)) {
+		throw new Error(`invalid transport "${value}" - use one of: ${TEAM_TRANSPORTS.join(", ")}`);
+	}
+	return value;
+}
+
+export function isMultiAgentV2(team) {
+	return team?.transport === "multi_agent_v2";
+}
+
+export function isCodexApp(team) {
+	return team?.transport === "codex_app";
+}
+
+export function assertTransport(team, transport, operation) {
+	if (team?.transport !== transport) {
+		throw new Error(`${operation} is only valid on ${transport} teams; this team's transport is "${team?.transport}"`);
+	}
+}
+
+export function parseTaskName(taskName) {
+	const trimmed = typeof taskName === "string" ? taskName.trim() : "";
+	if (!trimmed) throw new Error("member task name is required on multi_agent_v2 teams (--task-name)");
+	if (!TASK_NAME_PATTERN.test(trimmed)) {
+		throw new Error(`invalid task name "${trimmed}" - use lowercase letters, digits, and underscores`);
+	}
+	if (trimmed === "root") throw new Error('invalid task name "root" - it names the leader, never a member');
+	return trimmed;
+}
+
+export function agentPathForTaskName(taskName) {
+	return `${LEADER_AGENT_PATH}/${taskName}`;
+}

package/packages/omo-codex/plugin/components/teammode/skills/teammode/scripts/team.mjs

@@ -6,9 +6,10 @@
 // Zero external dependencies (node builtins only): runs identically under node and bun on
 // macOS, Linux, and Windows.
 //
-//   node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<sess>" [--session <id>] [--worktree] [--base-branch dev]
-//   node "<skill-root>/scripts/team.mjs" add-member  --team <id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <b>]
-//   node "<skill-root>/scripts/team.mjs" bind-thread  --team <id> --id A --thread <thread-id> [--cwd <path>]
+//   node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<sess>" [--transport multi_agent_v2|codex_app] [--session <id>] [--worktree] [--base-branch dev]
+//   node "<skill-root>/scripts/team.mjs" add-member  --team <id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--task-name <v2 task name>] [--branch <b>]
+//   node "<skill-root>/scripts/team.mjs" bind-agent   --team <id> --id A --agent-path /root/<task_name> [--cwd <path>]   (multi_agent_v2 teams)
+//   node "<skill-root>/scripts/team.mjs" bind-thread  --team <id> --id A --thread <thread-id> [--cwd <path>]            (codex_app teams)
 //   node "<skill-root>/scripts/team.mjs" member-prompt --team <id> --id A
 //   node "<skill-root>/scripts/team.mjs" set-status   --team <id> --id A --status reported|blocked|active|archived [--note "<...>"]
 //   node "<skill-root>/scripts/team.mjs" archive      --team <id> [--id A] [--note "<...>"]
@@ -25,6 +26,7 @@ import {
 	addMember,
 	archive,
 	assertSafeTeamDir,
+	bindAgent,
 	bindThread,
 	buildTeam,
 	clearMemberWorktree,
@@ -39,6 +41,7 @@ import {
 	writeGuideAtomic,
 	writeTeamAtomic,
 } from "./team-state.mjs";
+import { isMultiAgentV2, parseTeamTransport } from "./team-transport.mjs";
 import { addMemberWorktree, integrateMemberBranch, removeMemberWorktree } from "./team-worktree.mjs";
 
 function parseFlags(args) {
@@ -95,11 +98,20 @@ const handlers = {
 	async init(cwd, flags) {
 		const teamName = requireFlag(flags, "name");
 		const sessionName = requireFlag(flags, "session-name");
+		// Validate the transport BEFORE any directory exists so a bad value leaves no state behind.
+		// A valueless `--transport` parses as `true` and must fail loudly, never default silently.
+		const transport = parseTeamTransport(flags.transport === undefined ? undefined : flags.transport);
 		const sessionId = typeof flags.session === "string" ? flags.session : `team-${randomUUID().slice(0, 8)}`;
 		const dir = await ensureTeamDir(cwd, sessionId);
 		await withTeamLock(dir, "init", async () => {
 			if (await teamExists(dir)) {
-				process.stdout.write(`exists: ${dir} (left untouched; re-init is a safe no-op)\n`);
+				const existing = await readTeam(dir);
+				if (flags.transport !== undefined && existing.transport !== transport) {
+					throw new Error(
+						`team "${sessionId}" already exists with transport "${existing.transport}" - transport is immutable; keep using it or delete the team first`,
+					);
+				}
+				process.stdout.write(`exists: ${dir} (transport: ${existing.transport}; left untouched; re-init is a safe no-op)\n`);
 				return;
 			}
 			const team = buildTeam({
@@ -107,13 +119,15 @@ const handlers = {
 				sessionName,
 				sessionId,
 				dir,
+				transport,
 				worktreeEnabled: flags.worktree === true,
 				baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : "dev",
 			});
 			await persist(team, dir);
-			process.stdout.write(`created: ${dir}\n`);
+			const taskNameFlag = isMultiAgentV2(team) ? ' --task-name "<lowercase_digits_underscores>"' : "";
+			process.stdout.write(`created: ${dir} (transport: ${team.transport})\n`);
 			process.stdout.write(`team.json + guide.md written; artifacts/ ready. session id: ${sessionId}\n`);
-			process.stdout.write(`next: add-member --team ${sessionId} --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
+			process.stdout.write(`next: add-member --team ${sessionId} --id A --name "<short role>"${taskNameFlag} --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
 		});
 	},
 
@@ -127,13 +141,17 @@ const handlers = {
 			lens: requireFlag(flags, "lens"),
 			deliverable: typeof flags.deliverable === "string" ? flags.deliverable : "",
 			branch: typeof flags.branch === "string" ? flags.branch : null,
+			taskName: typeof flags["task-name"] === "string" ? flags["task-name"] : null,
 		};
 		const { team, member } = await mutateTeam(cwd, sessionId, "add-member", async (team, dir) => {
 			addMember(team, memberInput);
 			await persist(team, dir);
 			return { team, member: team.members.find((m) => m.id === memberId) };
 		});
-		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\nSend this as the new thread's first message (title the thread "${member.threadTitle}"):\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
+		const delivery = isMultiAgentV2(team)
+			? `Send this as spawn_agent message (task_name "${member.taskName}", fork_turns "none"), then bind-agent --agent-path "${member.agentPath}"`
+			: `Send this as the new thread's first message (title the thread "${member.threadTitle}")`;
+		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\n${delivery}:\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
 	},
 
 	async "bind-thread"(cwd, flags) {
@@ -151,6 +169,21 @@ const handlers = {
 		process.stdout.write(`bound member ${flags.id} to thread ${flags.thread}.\n`);
 	},
 
+	async "bind-agent"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const input = {
+			id: requireFlag(flags, "id"),
+			agentPath: requireFlag(flags, "agent-path"),
+			cwd: typeof flags.cwd === "string" ? flags.cwd : null,
+			worktreePath: typeof flags["worktree-path"] === "string" ? flags["worktree-path"] : null,
+		};
+		await mutateTeam(cwd, sessionId, "bind-agent", async (team, dir) => {
+			bindAgent(team, input);
+			await persist(team, dir);
+		});
+		process.stdout.write(`bound member ${flags.id} to agent ${flags["agent-path"]}.\n`);
+	},
+
 	async "member-prompt"(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
 		const { team } = await loadTeam(cwd, sessionId);
@@ -175,19 +208,24 @@ const handlers = {
 		const sessionId = requireFlag(flags, "team");
 		const memberId = requireFlag(flags, "id");
 		const baseBranch = typeof flags["base-branch"] === "string" ? flags["base-branch"] : null;
-		const { member, result } = await mutateTeam(cwd, sessionId, "worktree-add", async (team, dir) => {
+		const { team, member, result } = await mutateTeam(cwd, sessionId, "worktree-add", async (team, dir) => {
 			const member = memberOrThrow(team, memberId);
 			const result = addMemberWorktree(cwd, team, member, { baseBranch });
 			setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
 			await persist(team, dir);
-			return { member, result };
+			return { team, member, result };
 		});
 		const note = result.created ? "" : " (already exists)";
-		const thread = member.threadId
-			? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
-			: "\nMember thread is not bound yet; wait for the real Codex thread id, then bind-thread before sending bootstrap. After binding, send the member this worktree path.";
+		const v2 = isMultiAgentV2(team);
+		const followUp = v2
+			? member.status === "active"
+				? `\nMember agent: ${member.agentPath}\nSend it a followup_task to: cd "${result.path}"`
+				: `\nMember agent is not spawned yet; include this worktree path in its spawn_agent message, then bind-agent.`
+			: member.threadId
+				? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
+				: "\nMember thread is not bound yet; wait for the real Codex thread id, then bind-thread before sending bootstrap. After binding, send the member this worktree path.";
 		process.stdout.write(
-			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).${thread}\n`,
+			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).${followUp}\n`,
 		);
 	},
 
@@ -235,11 +273,19 @@ const handlers = {
 			id: typeof flags.id === "string" ? flags.id : null,
 			note: typeof flags.note === "string" ? flags.note : "",
 		};
-		await mutateTeam(cwd, sessionId, "archive", async (team, dir) => {
+		const team = await mutateTeam(cwd, sessionId, "archive", async (team, dir) => {
 			archive(team, input);
 			await persist(team, dir);
+			return team;
 		});
-		process.stdout.write(flags.id ? `archived member ${flags.id}\n` : `archived team ${sessionId} and closed all members\n`);
+		const v2 = isMultiAgentV2(team);
+		const teamSummary = v2
+			? `archived team ${sessionId}; V2 has no runtime archive operation - the durable team state is the archive (interrupt_agent any member still mid-turn)\n`
+			: `archived team ${sessionId} and closed all members\n`;
+		const memberSummary = v2
+			? `archived member ${flags.id} in team state; V2 has no runtime archive operation (interrupt_agent it if still mid-turn)\n`
+			: `archived member ${flags.id}\n`;
+		process.stdout.write(flags.id ? memberSummary : teamSummary);
 	},
 
 	async delete(cwd, flags) {
@@ -261,10 +307,18 @@ const handlers = {
 	async status(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
 		const { team } = await loadTeam(cwd, sessionId);
-		process.stdout.write(`Team ${team.teamName} [${team.status}] - leader: main session - ${team.members.length} member(s)\n`);
+		process.stdout.write(
+			`Team ${team.teamName} [${team.status}] - transport=${team.transport} - leader: main session - ${team.members.length} member(s)\n`,
+		);
 		for (const m of team.members) {
-			const thread = m.threadId ? ` thread=${m.threadId} link=${codexThreadLink(m.threadId)}` : "";
-			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${thread}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
+			const endpoint = isMultiAgentV2(team)
+				? m.agentPath
+					? ` agent=${m.agentPath}`
+					: ""
+				: m.threadId
+					? ` thread=${m.threadId} link=${codexThreadLink(m.threadId)}`
+					: "";
+			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${endpoint}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
 		}
 		if (isUnderstaffed(team)) {
 			process.stdout.write(

package/packages/omo-codex/plugin/components/teammode/test/thread-title-hook.test.ts

@@ -87,6 +87,29 @@ describe("thread title PostToolUse guidance", () => {
 		expect(actual).toBe("");
 	});
 
+	it("#given MultiAgentV2 spawn_agent completed #when the hook runs #then it leaves task-name identity untouched", () => {
+		// given
+		const output = runPostToolUseHook({
+			hook_event_name: "PostToolUse",
+			session_id: "s-team",
+			turn_id: "t-team",
+			transcript_path: null,
+			cwd: "/repo",
+			model: "gpt-5.6-sol",
+			permission_mode: "default",
+			tool_name: "spawn_agent",
+			tool_use_id: "tool-spawn-agent",
+			tool_input: { task_name: "runtime_core", message: "Inspect runtime state" },
+			tool_response: { task_name: "/root/runtime_core" },
+		});
+
+		// when
+		const actual = output;
+
+		// then
+		expect(actual).toBe("");
+	});
+
 	it("#given worktree-backed thread creation is pending #when the hook runs #then it tells Codex to wait for the real thread before bootstrapping", () => {
 		// given
 		const output = runPostToolUseHook({