oh-my-opencode 4.16.1 → 4.16.3

package/packages/omo-codex/plugin/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/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/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/skills/ultrawork/SKILL.md

@@ -266,6 +266,7 @@ Every `multi_agent_v1.spawn_agent` message is self-contained and starts with
 handoff. Use `fork_context: false` unless full history is truly
 required; paste only the context the child needs. Full-history forks can
 make the child continue old parent context instead of the delegated task.
+If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: `fork_context: false` becomes `fork_turns: "none"`, `send_input` becomes `send_message`, finished agents end on their own (no `close_agent`; `followup_task` re-tasks, `interrupt_agent` stops), and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity.
 
 # TOML-backed subagent routing compatibility
 Treat TOML-backed role routing as **routing-unverified**. The

package/packages/omo-codex/plugin/skills/ulw-loop/SKILL.md

@@ -46,4 +46,6 @@ The full workflow may mention OpenCode-style orchestration examples. In Codex, t
 | Wait for background result | `multi_agent_v1.wait_agent(...)` |
 | Clean up finished worker | `multi_agent_v1.close_agent(...)` |
 
+Flat `spawn_agent` requiring `task_name` instead (`multi_agent_v2`)? Rewrite rows: add `"task_name"`, `"fork_context":false` → `"fork_turns":"none"`, `wait_agent` takes only `timeout_ms`, no `close_agent` — finished agents end on their own.
+
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.

package/packages/omo-codex/plugin/skills/ulw-loop/references/full-workflow.md

@@ -161,7 +161,7 @@ Loop per goal. Cap at 5 cycles per goal. Cap identical same-criterion failures a
 2. Register atomic todos via `update_plan` — one ultra-granular step per action, `path: <action> for <criterion> - verify by <check>`. Call `update_plan` on every transition (start → `in_progress`, finish → `completed`); exactly one `in_progress`, mark completed immediately, never batch, never let the rendered plan lag behind reality.
 3. DELEGATE-IN-PARALLEL: dispatch every independent task in the wave at once via right-sized `multi_agent_v1.spawn_agent` workers (Delegation table). Each worker captures evidence failing-first: when the task touches EXISTING behavior, PIN it FIRST — a characterization test that asserts the current observable behavior and PASSES on the unchanged code, as rigorous as the new-behavior scenario (exact inputs, exact observable, exact assertion). Then RED through the cheapest faithful channel — a unit test where a seam exists, an integration/e2e test where the behavior lives in wiring, or the criterion's scenario captured failing when no test seam exists — failing for the RIGHT reason (no syntax/import error). A test that mirrors its implementation (mock-call assertions, pinned constants, cannot fail under plausible regression) is not evidence; use the scenario as the failing proof instead. Then the SMALLEST GREEN change; before GREEN work that depends on external review, PR, issue, or branch state, refresh current branch/PR/issue state, preserve existing ordering/policy, and separate compatibility detection from policy changes unless the goal explicitly asks to change policy. A GREEN far larger than the criterion implies means the proof was too coarse — instruct a split. Serialize only on a NAMED dependency.
 4. INTEGRATE + CRITICAL SELF-QA + GIT CHECKPOINT (EVERY WORKER RETURN): do NOT trust the worker's report. Read the diff yourself, re-run its tests, and run LSP diagnostics on the changed files. Treat "done" as a claim to disprove. If the diff drifts, the test is hollow, or evidence is missing, RESPAWN the worker with the specific failure context. Once the work unit is verified, use `git-master` before staging: inspect recent repository commits and touched-path history to infer commit language, Conventional Commit scope, message shape, and unit size. Stage only that unit's files and commit in the observed style; do not carry verified work forward into a later omnibus commit. If no git-tracked files changed or committing is unsafe, record the no-commit reason as evidence. Forward every finding/learning to subsequent workers.
-5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA worker (`worker`, `gpt-5.5`, `high`) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
+5. EXECUTE-AS-SCENARIO: ACTUALLY run the Manual-QA scenario the criterion named (channel table above). Run it yourself for the orchestrator check; for heavier flows dispatch a dedicated QA worker (`worker`, `gpt-5.6-sol`, `xhigh`) whose ONLY job is to drive the channel and write the artifact to the named evidence path. If the scenario FAILS, respawn the implementing worker with the captured failure — do not hand-patch around it.
 6. CAPTURE: collect the observable artifact path: transcript, stdout, screenshot, assertion, status+body, diff, or parsed dump. No artifact written at the evidence path — not done; record BLOCKED and respawn QA.
 7. CLEAN (PAIRED, NEVER SKIP): tear down every runtime artifact step 5 spawned BEFORE recording — server PIDs (`kill`, verify `kill -0` fails), `tmux` sessions (`tmux kill-session -t ulw-qa-<criterion>`; confirm `tmux ls`), browser / Playwright contexts (`.close()`), containers (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env vars, AND `multi_agent_v1.close_agent` on every finished worker. Register each teardown as its own todo the moment the QA spawns the resource (scripts, tmux assets, browsers / agent-browser sessions, PIDs, ports) so none is forgotten. Embed a one-line cleanup receipt in the evidence string, e.g. `cleanup: killed 12345; tmux kill-session ulw-qa-foo; rm -rf /tmp/ulw.aB12cD; multi_agent_v1.close_agent w-3`. Missing receipt → record BLOCKED, not PASS.
 8. RECORD exactly one result:

package/packages/omo-codex/plugin/skills/ulw-plan/SKILL.md

@@ -67,6 +67,8 @@ Fan out read-only research before deciding. Every spawn names DELIVERABLE / SCOP
 multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...","agent_type":"explorer","fork_context":false})
 ```
 
+If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: add `"task_name":"<lowercase_digits_underscores>"`, replace `"fork_context":false` with `"fork_turns":"none"`, and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity (finished agents end on their own).
+
 Spawn every independent child for the current wave first. After the wave
 is launched, use `multi_agent_v1.wait_agent` for each child until each
 reaches terminal status. A timeout is not terminal status. Do not start dependent planning, drafting, approval-gate work, or final handoff until each child result is integrated or recorded as inconclusive.

package/packages/omo-codex/plugin/skills/ulw-plan/references/full-workflow.md

@@ -85,7 +85,7 @@ Runs in parallel; ALL must APPROVE; surface results and wait for the user's expl
 - UNCLEAR: run the high-accuracy review AUTOMATICALLY before presenting (unless Classify=Trivial), then present a brief that LEADS with the derived approach and the adopted defaults; still wait for the user's explicit okay.
 
 ### High-accuracy review (dual review)
-The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Codex CLI review on gpt-5.5 at xhigh reasoning, run in a disposable isolated workspace and `CODEX_HOME` with the harness's normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled) - never a second `momus` while a round is in flight. After both verdicts return, fix every cited issue and resubmit both fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
+The high-accuracy review is DUAL and both passes must return OKAY before handoff: (1) the native `momus` reviewer subagent, and (2) an independent Codex CLI review on gpt-5.6-sol at xhigh reasoning, run in a disposable isolated workspace and `CODEX_HOME` with the harness's normal approval and sandbox policy. Do not add flags that disable approvals or sandboxing. Momus runs at Ultra and may take substantially longer than other agents. One round = exactly ONE `momus` + ONE independent review, dispatched together against the COMPLETE plan file (todos + TL;DR filled). Keep Momus in flight and wait for its terminal result: elapsed time alone never justifies cancelling, duplicating, replacing, or treating it as failed. After both verdicts return, fix every cited issue and resubmit both fresh until each approves. CLEAR: runs when the user opts in or `review_required: true`. UNCLEAR: runs automatically unless Classify=Trivial.
 
 The draft must record the native Momus session/result, the independent Codex CLI review command/result, and the fix/retry summary. Do not say "high-accuracy review completed" unless both receipts exist and both final verdicts are unconditional approval.
 
@@ -96,6 +96,8 @@ Every spawn starts with `TASK:`, then DELIVERABLE / SCOPE / VERIFY inside `messa
 multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. DELIVERABLE: ... SCOPE: ... VERIFY: ...","agent_type":"explorer","fork_context":false})
 ```
 
+If your tool list has a flat `spawn_agent` with a required `task_name` instead of `multi_agent_v1.*` (`multi_agent_v2`), rewrite: add `"task_name":"<lowercase_digits_underscores>"`, replace `"fork_context":false` with `"fork_turns":"none"`, and `wait_agent` takes only `timeout_ms`, returning on any child mailbox activity (finished agents end on their own — skip the close step).
+
 Roles: `explorer`, `librarian`, `metis`, `momus`. Spawn long plan/reviewer agents in the background and poll with short waits; require the child to send `WORKING: <task> - <phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A wait timeout only means no new mailbox update arrived; treat a running child as alive. Fall back only when the child completed without the deliverable, is ack-only after followup, explicitly `BLOCKED:`, or no longer running; then respawn a smaller `fork_context: false` job. Close each agent after integrating its result.
 
 ## Stop rules

package/packages/omo-codex/plugin/skills/ulw-research/SKILL.md

@@ -15,11 +15,11 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
@@ -69,7 +69,7 @@ Observation candidates and claim candidates travel back from workers as message
 
 ## Run the swarm as a cooperating team
 
-Saturation research defaults to teammode, not isolated fire-and-forget workers: a lead one worker surfaces almost always reshapes what another should search next. When your harness gives you real cooperating members — Codex: the `teammode` skill (`codex_app` threads); OpenCode: `team_mode` — run this swarm as a team. Fall back to the background-worker swarm below only when team mode is unavailable, or the axes are genuinely independent with no cross-pollination expected.
+Saturation research defaults to teammode, not isolated fire-and-forget workers: a lead one worker surfaces almost always reshapes what another should search next. When your harness gives you real cooperating members — Codex: the `teammode` skill (MultiAgentV2 agents, or `codex_app` threads as its fallback); OpenCode: `team_mode` — run this swarm as a team. Fall back to the background-worker swarm below only when team mode is unavailable, or the axes are genuinely independent with no cross-pollination expected.
 
 - **One member per axis — by part, ownership, or perspective, never a job title.** Each Phase 0 axis is one member owning one concrete slice: a codebase part, a source territory, or a question lens. No two members share an angle. "Backend researcher" or "the web person" gives no real boundary and invites overlap — name what the member owns.
 - **Many teammates by default.** Prefer a larger roster, usually 5-8 teammates, whenever the axes can be made distinct. Add at least one skeptic or red-team perspective for hyperdebate/ultradebate: cross-critique claims, evidence quality, synthesis structure, and visual-report choices before they reach the final deliverable.

package/packages/omo-codex/plugin/skills/visual-qa/SKILL.md

@@ -15,11 +15,11 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` |
 | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
 | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
-| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list |
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. `agent_type` works the same on both surfaces. If a code block below conflicts with this section, this section wins.
 
 When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
 
@@ -271,7 +271,7 @@ If any page fails, you are not done: fix it, re-capture the full set, re-dispatc
 
 Run this step IN ADDITION to Steps 1-4 when the original user task has a concrete visual target: "clone this site", "move this Figma design to code", "rebuild this screen", "make it look exactly like X", or "build this Imagen/Stitch/generated mockup and overview". For these tasks the normal dual-oracle is necessary but NOT sufficient. After it returns, run the following TWO additional MANDATORY verifications and LOOP until BOTH pass.
 
-1. Pixel-perfect design-compare subagent (visual oracle). Dispatch a focused, read-only design-compare reviewer (recommend `gpt-5.5` with medium reasoning). It must crop/zoom BOTH the reference (target / Figma export / source-site screenshot / generated page snapshot) and the ACTUAL screenshot into matching regions and read them **pixel-by-pixel** - header, nav, each card, spacing, type ramp, color tokens - not at a glance. It must also compare the overview text or annotations against the rendered content and DOM text. Anchor every claim with the bundled tool:
+1. Pixel-perfect design-compare subagent (visual oracle). Dispatch a focused, read-only design-compare reviewer (recommend `gpt-5.6-sol` with xhigh reasoning). It must crop/zoom BOTH the reference (target / Figma export / source-site screenshot / generated page snapshot) and the ACTUAL screenshot into matching regions and read them **pixel-by-pixel** - header, nav, each card, spacing, type ramp, color tokens - not at a glance. It must also compare the overview text or annotations against the rendered content and DOM text. Anchor every claim with the bundled tool:
 
 ```
 node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> <actual.png>