oh-my-opencode 4.16.1 → 4.16.3

package/packages/omo-codex/plugin/scripts/migrate-codex-config/multi-agent-v2-guard.mjs

@@ -1,20 +1,31 @@
 /**
- * Runtime migration: force `[features.multi_agent_v2]` to `enabled = false`.
+ * Runtime migration for `[features.multi_agent_v2]`.
  *
- * Runs on every Codex SessionStart (via auto-update's config migration) so
- * multi-agent V2 stays off regardless of how it was turned on: an
- * installer-forced `enabled = true`, a missing `enabled` key the runtime
- * would resolve per model, or the `[features]` boolean shorthand
- * `multi_agent_v2 = true` (removed here because a boolean key and a
- * `[features.multi_agent_v2]` table for the same name are conflicting TOML).
+ * Historical behavior (openai/codex#26753): force `enabled = false` on every
+ * SessionStart because enabling V2 made every turn 400 with encrypted
+ * spawn_agent parameters on models that were not configured for encrypted
+ * tool use. OpenAI closed that as NOT_PLANNED (V2 under development).
  *
- * Upstream basis: openai/codex#26753 — with the flag on, EVERY turn fails
- * with a 400 ("spawn_agent declares encrypted parameters but is not
- * configured for encrypted tool use by this model"), even on prompts that
- * never touch subagents. OpenAI closed it NOT_PLANNED stating V2 is under
- * development, not recommended, and bug reports are not accepted. Same
- * failure class still being reported (openai/codex#27205).
+ * GPT-5.6 models that declare `multi_agent_version: "v2"` in the Codex model
+ * catalog invert that failure mode: forcing `enabled = false` makes every
+ * turn 400 with a reserved `collaboration.spawn_agent` schema mismatch
+ * (lazycodex#118 / oh-my-openagent#6002 / openai/codex#31097), and
+ * `hide_spawn_agent_metadata = false` (written by OMO installers <= 4.15.x)
+ * mismatches the same reserved schema by re-adding agent_type/model
+ * properties to spawn_agent. For those models this guard clears the managed
+ * disable and the stale metadata override, leaving V2 unset so Codex can
+ * follow model metadata.
+ *
+ * When the selected model is unknown or declares V1, keep the #26753
+ * force-disable path.
+ *
+ * Opt out of the whole migration with LAZYCODEX_CONFIG_MIGRATION_DISABLED=1
+ * (or OMO_CODEX_CONFIG_MIGRATION_DISABLED=1).
  */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+
 const MANAGED_COMMENT_MARKER = "openai/codex#26753";
 const MANAGED_DISABLE_COMMENT = [
 	"# Managed by LazyCodex: multi_agent_v2 is re-disabled on every Codex session start",
@@ -23,26 +34,192 @@ const MANAGED_DISABLE_COMMENT = [
 	"",
 ].join("\n");
 
-export function forceDisableMultiAgentV2(config) {
-	let result = removeFeaturesShorthand(config);
+/**
+ * @param {string} config
+ * @param {{
+ *   multiAgentVersion?: string | null,
+ *   sessionModel?: string | null,
+ *   requireSessionModel?: boolean,
+ *   env?: NodeJS.ProcessEnv,
+ *   modelsCachePath?: string,
+ *   configPath?: string,
+ * }} [options]
+ */
+export function forceDisableMultiAgentV2(config, options = {}) {
+	// Always normalize the legacy `[features]` boolean shorthand first: leaving
+	// `multi_agent_v2 = true|false` in place while a later guard appends the
+	// `[features.multi_agent_v2]` table would define the same name as both a
+	// scalar and a table, which Codex rejects as invalid TOML.
+	const normalized = removeFeaturesShorthand(config);
+	const sessionModel = normalizeModel(options.sessionModel);
+	const multiAgentVersion =
+		options.multiAgentVersion !== undefined
+			? options.multiAgentVersion
+			: resolveMultiAgentVersionFromConfig(normalized, options);
+	const effectiveModel = sessionModel || readRootModel(normalized);
+
+	if (prefersMultiAgentV2(multiAgentVersion, effectiveModel)) {
+		return clearMultiAgentV2DisableForReservedSchema(normalized);
+	}
+
+	// SessionStart can run with an override model (`codex -m gpt-5.6-terra`) while
+	// config.toml still lists a different default. If we cannot see the effective
+	// session model, do not force-disable — writing enabled=false would break a
+	// GPT-5.6 reserved collaboration.spawn_agent session.
+	if (options.requireSessionModel === true && !sessionModel) {
+		return normalized;
+	}
+
+	// No model evidence at all (no session model AND no root `model` in
+	// config.toml — Codex Desktop selects the model in the UI): config alone
+	// cannot prove the session is not a GPT-5.6 reserved-schema model, and
+	// writing `enabled = false` would 400 every turn on those sessions
+	// (#6002). Leave the enable state untouched.
+	if (multiAgentVersion == null && !sessionModel && !readRootModel(normalized)) {
+		return normalized;
+	}
+
+	// Unknown catalog entry for an explicit session model: skip force-disable
+	// rather than assume the legacy encrypted-V2 failure mode.
+	if (sessionModel && multiAgentVersion == null) {
+		return normalized;
+	}
+
+	return forceDisableLegacyEncryptedV2(normalized);
+}
+
+/**
+ * True when the effective model should run MultiAgentV2: the catalog says
+ * "v2", or the catalog is unavailable but the model is a GPT-5.6 family
+ * model (which reserves the collaboration.spawn_agent schema).
+ * @param {"v1" | "v2" | null | undefined} multiAgentVersion
+ * @param {string | null | undefined} sessionModel
+ */
+export function prefersMultiAgentV2(multiAgentVersion, sessionModel) {
+	return multiAgentVersion === "v2" || (multiAgentVersion == null && isGpt56Family(normalizeModel(sessionModel)));
+}
+
+/**
+ * Resolve the effective model against Codex `models_cache.json`.
+ * Prefers SessionStart `model` over the root `model` in config.toml.
+ * @param {string} config
+ * @param {{ sessionModel?: string | null, env?: NodeJS.ProcessEnv, modelsCachePath?: string, configPath?: string }} [options]
+ * @returns {"v1" | "v2" | null}
+ */
+export function resolveMultiAgentVersionFromConfig(config, options = {}) {
+	const model = normalizeModel(options.sessionModel) || readRootModel(config);
+	if (!model) return null;
+	const version = resolveMultiAgentVersionForModel(model, {
+		...options,
+		modelsCachePath: options.modelsCachePath?.trim() || resolveModelCatalogPath(readRootModelCatalogPath(config), options) || undefined,
+	});
+	return version ?? (isGpt56Family(model) ? "v2" : null);
+}
+
+/**
+ * @param {string} model
+ * @param {{ env?: NodeJS.ProcessEnv, modelsCachePath?: string }} [options]
+ * @returns {"v1" | "v2" | null}
+ */
+export function resolveMultiAgentVersionForModel(model, options = {}) {
+	const cachePath =
+		options.modelsCachePath?.trim() ||
+		join(options.env?.CODEX_HOME?.trim() || join(homedir(), ".codex"), "models_cache.json");
+
+	try {
+		const cache = JSON.parse(readFileSync(cachePath, "utf8"));
+		const models = Array.isArray(cache?.models) ? cache.models : [];
+		const entry = models.find((item) => item?.slug === model || item?.id === model);
+		const version = entry?.multi_agent_version;
+		if (version === "v1" || version === "v2") return version;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export function readRootModel(config) {
+	const double = config.match(/^\s*model\s*=\s*"([^"]+)"/m);
+	if (double) return double[1];
+	const single = config.match(/^\s*model\s*=\s*'([^']+)'/m);
+	return single?.[1] ?? null;
+}
+
+// Codex documents `model_catalog_json` as a COMPLETE replacement for the
+// fetched models_cache.json (codex-rs/core/src/config/mod.rs load_model_catalog
+// -> load_catalog_json -> ModelsResponse). When set, Codex resolves the model
+// only from that file, so the guard must too — otherwise Codex and the guard
+// disagree on the multi-agent version (lazycodex#120).
+export function readRootModelCatalogPath(config) {
+	const double = config.match(/^\s*model_catalog_json\s*=\s*"([^"]+)"/m);
+	if (double) return double[1];
+	const single = config.match(/^\s*model_catalog_json\s*=\s*'([^']+)'/m);
+	return single?.[1] ?? null;
+}
+
+function resolveModelCatalogPath(configuredPath, options) {
+	const trimmed = normalizeModel(configuredPath);
+	if (!trimmed) return null;
+	if (isAbsolute(trimmed)) return trimmed;
+	const baseDir = options.configPath ? dirname(options.configPath) : options.env?.CODEX_HOME?.trim() || join(homedir(), ".codex");
+	return join(baseDir, trimmed);
+}
+
+function normalizeModel(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+
+function isGpt56Family(model) {
+	return typeof model === "string" && /^gpt-5\.6\b/i.test(model);
+}
+
+function clearMultiAgentV2DisableForReservedSchema(config) {
+	// `config` arrives shorthand-normalized from forceDisableMultiAgentV2.
+	const result = removeManagedDisableComments(config);
+
 	const section = findSection(result, "[features.multi_agent_v2]");
+	if (!section) return result;
+
+	// Two settings poison the reserved collaboration.spawn_agent schema on V2
+	// models (verified against codex-cli 0.144.1 + gpt-5.6-sol):
+	// - `enabled = false` forces the legacy V1 tool surface on some Codex
+	//   versions (#6002's failure shape);
+	// - `hide_spawn_agent_metadata = false` (written by OMO installers
+	//   <= 4.15.x to expose agent_type) re-adds agent_type/model/... to
+	//   spawn_agent, mismatching the reserved schema -> HTTP 400 every turn.
+	// Remove both; `hide_spawn_agent_metadata = true` matches the Codex
+	// default and is left alone.
+	const cleared = section.text
+		.replace(/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?\n?/gm, "")
+		.replace(/^\s*hide_spawn_agent_metadata\s*=\s*false[ \t]*(?:#[^\n]*)?\n?/gm, "");
+	if (cleared === section.text) return result;
+	return result.slice(0, section.start) + cleared + result.slice(section.end);
+}
+
+// `config` arrives shorthand-normalized from forceDisableMultiAgentV2.
+function forceDisableLegacyEncryptedV2(config) {
+	const section = findSection(config, "[features.multi_agent_v2]");
 
 	if (!section) {
-		return ensureManagedComment(appendDisabledSection(result));
+		return ensureManagedComment(appendDisabledSection(config));
 	}
 
 	const enabledTruePattern = /^(\s*)enabled\s*=\s*true[ \t]*(#[^\n]*)?$/m;
 	if (enabledTruePattern.test(section.text)) {
-		const patched = section.text.replace(enabledTruePattern, (_match, indent, comment) => comment ? `${indent}enabled = false ${comment}` : `${indent}enabled = false`);
-		return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+		const patched = section.text.replace(enabledTruePattern, (_match, indent, comment) =>
+			comment ? `${indent}enabled = false ${comment}` : `${indent}enabled = false`,
+		);
+		return ensureManagedComment(config.slice(0, section.start) + patched + config.slice(section.end));
 	}
 
-	if (/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text)) return result;
+	if (/^\s*enabled\s*=\s*false[ \t]*(?:#[^\n]*)?$/m.test(section.text)) return config;
 
 	const headerEnd = section.text.indexOf("\n");
 	const insertAt = headerEnd === -1 ? section.text.length : headerEnd + 1;
 	const patched = `${section.text.slice(0, insertAt)}${headerEnd === -1 ? "\n" : ""}enabled = false\n${section.text.slice(insertAt)}`;
-	return ensureManagedComment(result.slice(0, section.start) + patched + result.slice(section.end));
+	return ensureManagedComment(config.slice(0, section.start) + patched + config.slice(section.end));
 }
 
 function ensureManagedComment(config) {
@@ -52,6 +229,30 @@ function ensureManagedComment(config) {
 	return config.slice(0, section.start) + MANAGED_DISABLE_COMMENT + config.slice(section.start);
 }
 
+function removeManagedDisableComments(config) {
+	if (!config.includes(MANAGED_COMMENT_MARKER) && !config.includes("Managed by LazyCodex: multi_agent_v2")) {
+		return config;
+	}
+
+	const lines = config.split("\n");
+	const kept = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (
+			trimmed.startsWith("#") &&
+			(trimmed.includes(MANAGED_COMMENT_MARKER) ||
+				trimmed.includes("Managed by LazyCodex: multi_agent_v2") ||
+				trimmed.includes("because enabling it fails every turn with HTTP 400") ||
+				trimmed.includes("LAZYCODEX_CONFIG_MIGRATION_DISABLED=1") ||
+				trimmed.includes("OMO_CODEX_CONFIG_MIGRATION_DISABLED=1"))
+		) {
+			continue;
+		}
+		kept.push(line);
+	}
+	return kept.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
 function removeFeaturesShorthand(config) {
 	const section = findSection(config, "[features]");
 	if (!section) return config;

package/packages/omo-codex/plugin/scripts/migrate-codex-config/subagent-limit-guard.mjs

@@ -1,9 +1,59 @@
+import { prefersMultiAgentV2, readRootModel, resolveMultiAgentVersionFromConfig } from "./multi-agent-v2-guard.mjs";
+
 const CODEX_AGENTS_HEADER = "[agents]";
 const CODEX_MULTI_AGENT_V2_HEADER = "[features.multi_agent_v2]";
 const CODEX_SUBAGENT_THREAD_LIMIT = "1000";
 
-export function ensureSubagentConcurrencyLimit(config) {
-	return ensureMultiAgentV2ThreadLimit(ensureAgentsMaxThreads(config));
+/**
+ * Ensure subagent concurrency limits without writing settings that conflict
+ * with MultiAgentV2. When the selected model prefers V2 (catalog `v2`, or a
+ * GPT-5.6 family session model with the catalog unavailable) or V2 is already
+ * enabled in config, skip `agents.max_threads` because Codex rejects that key
+ * while features.multi_agent_v2 is enabled.
+ *
+ * When no model is resolvable at all (no session model and no root `model`
+ * in config.toml — Codex Desktop selects the model in the UI), never
+ * introduce `agents.max_threads`: it hard-fails thread/start on
+ * MultiAgentV2 sessions. An existing cap is still raised in place so the
+ * legacy low-cap repair keeps working and a hand-removed key stays removed.
+ *
+ * @param {string} config
+ * @param {{ multiAgentVersion?: string | null, sessionModel?: string | null, env?: NodeJS.ProcessEnv, modelsCachePath?: string }} [options]
+ */
+export function ensureSubagentConcurrencyLimit(config, options = {}) {
+	const multiAgentVersion =
+		options.multiAgentVersion !== undefined
+			? options.multiAgentVersion
+			: resolveMultiAgentVersionFromConfig(config, options);
+	const v2Preferred = prefersMultiAgentV2(multiAgentVersion, options.sessionModel) || isMultiAgentV2Enabled(config);
+
+	let result = config;
+	if (v2Preferred) {
+		result = removeAgentsMaxThreads(result);
+	} else if (multiAgentVersion == null && !hasModelEvidence(config, options)) {
+		result = raiseExistingAgentsMaxThreads(result);
+	} else {
+		result = ensureAgentsMaxThreads(result);
+	}
+	return ensureMultiAgentV2ThreadLimit(result);
+}
+
+function hasModelEvidence(config, options) {
+	const sessionModel = typeof options.sessionModel === "string" ? options.sessionModel.trim() : "";
+	return sessionModel.length > 0 || readRootModel(config) !== null;
+}
+
+function isMultiAgentV2Enabled(config) {
+	const section = findSection(config, CODEX_MULTI_AGENT_V2_HEADER);
+	if (!section) return false;
+	return /^\s*enabled\s*=\s*true[ \t]*(?:#[^\n]*)?$/m.test(section.text);
+}
+
+function raiseExistingAgentsMaxThreads(config) {
+	const section = findSection(config, CODEX_AGENTS_HEADER);
+	if (!section) return config;
+	if (!/^\s*max_threads\s*=/m.test(section.text)) return config;
+	return replaceOrInsertSetting(config, section, "max_threads", CODEX_SUBAGENT_THREAD_LIMIT);
 }
 
 function ensureAgentsMaxThreads(config) {
@@ -12,6 +62,22 @@ function ensureAgentsMaxThreads(config) {
 	return replaceOrInsertSetting(config, section, "max_threads", CODEX_SUBAGENT_THREAD_LIMIT);
 }
 
+function removeAgentsMaxThreads(config) {
+	const section = findSection(config, CODEX_AGENTS_HEADER);
+	if (!section) return config;
+	if (!/^\s*max_threads\s*=/m.test(section.text)) return config;
+
+	const patched = section.text.replace(/^\s*max_threads\s*=\s*[^\n]*\n?/m, "");
+	const bodyLines = patched
+		.split("\n")
+		.slice(1)
+		.filter((line) => line.trim() !== "");
+	if (bodyLines.length === 0) {
+		return config.slice(0, section.start) + config.slice(section.end).replace(/^\n+/, "");
+	}
+	return config.slice(0, section.start) + patched + config.slice(section.end);
+}
+
 function ensureMultiAgentV2ThreadLimit(config) {
 	const section = findSection(config, CODEX_MULTI_AGENT_V2_HEADER);
 	if (!section) {
@@ -26,7 +92,9 @@ function ensureMultiAgentV2ThreadLimit(config) {
 function replaceOrInsertSetting(config, section, key, value) {
 	const pattern = new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*=\\s*[^\\n#]*(#[^\\n]*)?$`, "m");
 	if (pattern.test(section.text)) {
-		const patched = section.text.replace(pattern, (_match, indent, comment) => comment ? `${indent}${key} = ${value} ${comment}` : `${indent}${key} = ${value}`);
+		const patched = section.text.replace(pattern, (_match, indent, comment) =>
+			comment ? `${indent}${key} = ${value} ${comment}` : `${indent}${key} = ${value}`,
+		);
 		return config.slice(0, section.start) + patched + config.slice(section.end);
 	}
 

package/packages/omo-codex/plugin/scripts/migrate-codex-config.mjs

@@ -2,13 +2,16 @@
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { pathToFileURL } from "node:url";
 
+import { isCliEntry } from "./entry-guard.mjs";
 import { FALLBACK_CATALOG, readModelCatalog } from "./migrate-codex-config/catalog.mjs";
 import { configPaths } from "./migrate-codex-config/config-paths.mjs";
 import { removeStaleContext7PlaceholderMcpServer } from "./migrate-codex-config/context7-placeholder-guard.mjs";
 import { removeUnsupportedRootMultiAgentMode } from "./migrate-codex-config/multi-agent-mode-guard.mjs";
-import { forceDisableMultiAgentV2 } from "./migrate-codex-config/multi-agent-v2-guard.mjs";
+import {
+	forceDisableMultiAgentV2,
+	resolveMultiAgentVersionFromConfig,
+} from "./migrate-codex-config/multi-agent-v2-guard.mjs";
 import { ensureCodexReasoningConfig as applyReasoningProfile, readRootSettings } from "./migrate-codex-config/root-settings.mjs";
 import { readState, resolveStatePath, writeState } from "./migrate-codex-config/state.mjs";
 import { ensureSubagentConcurrencyLimit } from "./migrate-codex-config/subagent-limit-guard.mjs";
@@ -19,7 +22,12 @@ export function ensureCodexReasoningConfig(config, profile = FALLBACK_CATALOG.cu
 	return applyReasoningProfile(config, profile);
 }
 
-export async function migrateCodexConfig({ env = process.env, cwd = process.cwd() } = {}) {
+export async function migrateCodexConfig({
+	env = process.env,
+	cwd = process.cwd(),
+	sessionModel = null,
+	requireSessionModel = false,
+} = {}) {
 	const catalog = await readModelCatalog(env);
 	const statePath = resolveStatePath(env);
 	const state = await readState(statePath);
@@ -31,6 +39,9 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 		const result = await migrateConfigFile(configPath, {
 			catalog,
 			previousState: state.files?.[configPath],
+			env,
+			sessionModel,
+			requireSessionModel,
 		});
 		if (result.changed) changed.push(configPath);
 		if (result.multiAgentModeChanged) modeChanged.push(configPath);
@@ -44,7 +55,16 @@ export async function migrateCodexConfig({ env = process.env, cwd = process.cwd(
 	return { changed, modeChanged };
 }
 
-export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG, previousState } = {}) {
+export async function migrateConfigFile(
+	configPath,
+	{
+		catalog = FALLBACK_CATALOG,
+		previousState,
+		env = process.env,
+		sessionModel = null,
+		requireSessionModel = false,
+	} = {},
+) {
 	const before = await readConfig(configPath);
 	const decision = shouldApplyCatalog(before, catalog, previousState);
 
@@ -56,7 +76,12 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 		reasoningApplied = config !== before;
 	}
 
-	const afterMultiAgentGuard = forceDisableMultiAgentV2(config);
+	const multiAgentOptions = { env, sessionModel, requireSessionModel, configPath };
+	const multiAgentVersion = resolveMultiAgentVersionFromConfig(config, multiAgentOptions);
+	const afterMultiAgentGuard = forceDisableMultiAgentV2(config, {
+		...multiAgentOptions,
+		multiAgentVersion,
+	});
 	const multiAgentChanged = afterMultiAgentGuard !== config;
 	if (multiAgentChanged) config = afterMultiAgentGuard;
 
@@ -68,7 +93,10 @@ export async function migrateConfigFile(configPath, { catalog = FALLBACK_CATALOG
 	const context7PlaceholderChanged = afterContext7PlaceholderGuard !== config;
 	if (context7PlaceholderChanged) config = afterContext7PlaceholderGuard;
 
-	const afterSubagentLimit = ensureSubagentConcurrencyLimit(config);
+	const afterSubagentLimit = ensureSubagentConcurrencyLimit(config, {
+		...multiAgentOptions,
+		multiAgentVersion,
+	});
 	const subagentLimitChanged = afterSubagentLimit !== config;
 	if (subagentLimitChanged) config = afterSubagentLimit;
 
@@ -117,7 +145,7 @@ async function readConfig(configPath) {
 	}
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isCliEntry(import.meta.url)) {
 	migrateCodexConfig().catch((error) => {
 		if (!(error instanceof Error)) throw error;
 		process.exit(0);

package/packages/omo-codex/plugin/scripts/migrate-omo-sot.mjs

@@ -3,8 +3,8 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { pathToFileURL } from "node:url";
 
+import { isCliEntry } from "./entry-guard.mjs";
 import { addCodexCodegraphValues, hasOwn, isRecord, recordAt } from "./migrate-omo-sot/editor.mjs";
 import { parseJsonc } from "./migrate-omo-sot/jsonc.mjs";
 import { SCAFFOLD } from "./migrate-omo-sot/scaffold.mjs";
@@ -109,7 +109,7 @@ function isValidCodegraphValue(key, value) {
 	return typeof value === "boolean";
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isCliEntry(import.meta.url)) {
 	migrateOmoSotConfig({ seed: process.argv.includes("--seed") })
 		.then((result) => {
 			for (const warning of result.warnings) process.stderr.write(`${warning}\n`);

package/packages/omo-codex/plugin/scripts/sync-hook-status-messages.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { pathToFileURL } from "node:url";
 import { fileURLToPath } from "node:url";
 
+import { isCliEntry } from "./entry-guard.mjs";
 import { formatLazyCodexHookStatusMessage, normalizeLazyCodexHookStatusLabel } from "./hook-status-message.mjs";
 
 const defaultRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -102,6 +102,6 @@ export async function syncHookStatusMessages(root = defaultRoot, options = {}) {
 	}
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isCliEntry(import.meta.url)) {
 	await syncHookStatusMessages();
 }

package/packages/omo-codex/plugin/scripts/sync-skills.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+
+import { isCliEntry } from "./entry-guard.mjs";
 import { sharedSkillsRootPath } from "@oh-my-opencode/shared-skills";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -36,7 +38,7 @@ function shouldCopySkillSource(source) {
 
 const opencodeOnlyOrchestrationPattern = /\b(?:call_omo_agent|background_output|team_[a-z_]+|task)\s*\(/;
 
-const codexHarnessToolCompatibility = `## Codex Harness Tool Compatibility
+export const codexHarnessToolCompatibility = `## Codex Harness Tool Compatibility
 
 This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as \`call_omo_agent(...)\`, \`task(...)\`, \`background_output(...)\`, or \`team_*(...)\` literally. Translate those examples to Codex native tools:
 
@@ -48,11 +50,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.
 
@@ -263,6 +265,6 @@ async function syncSkills() {
 	}
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isCliEntry(import.meta.url)) {
 	await syncSkills();
 }

package/packages/omo-codex/plugin/scripts/sync-version.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+
+import { isCliEntry } from "./entry-guard.mjs";
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const defaultPluginRoot = dirname(scriptDir);
@@ -88,7 +90,7 @@ export async function syncVersion(options = {}) {
 	return { version, targets, changed };
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isCliEntry(import.meta.url)) {
 	const result = await syncVersion();
 	console.log(`Synced OMO Codex manifests to version ${result.version} (${result.changed.length} updated)`);
 }

package/packages/omo-codex/plugin/skills/init-deep/SKILL.md

@@ -14,11 +14,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.
 

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

package/packages/omo-codex/plugin/skills/remove-ai-slops/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.