oh-my-opencode 4.16.1 → 4.16.2

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

@@ -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

@@ -19,7 +19,7 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 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/visual-qa/SKILL.md

@@ -19,7 +19,7 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 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/test/aggregate-plugin-fixture.mjs

@@ -88,7 +88,7 @@ export function findSpawnAgentCallsWithoutForkContextFalse(content) {
 	const regex = /spawn_agent\(([^)]*)\)/g;
 	for (const match of content.matchAll(regex)) {
 		const call = match[0];
-		if (!/"fork_context"\s*:\s*false|fork_context:\s*false|fork_context=false/.test(call)) {
+		if (!/"fork_context"\s*:\s*false|fork_context:\s*false|fork_context=false|"fork_turns"\s*:\s*"none"|fork_turns:\s*"none"|fork_turns="none"/.test(call)) {
 			missingForkContext.push(call);
 		}
 	}

package/packages/omo-codex/plugin/test/auto-update.test.mjs

@@ -2,9 +2,10 @@ import assert from "node:assert/strict";
 import { mkdir, mkdtemp, readFile, symlink, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { PassThrough } from "node:stream";
 import test from "node:test";
 
-import { resolveAutoUpdatePlan, resolveLazyCodexUpdatePlan, runAutoUpdateCheck } from "../scripts/auto-update.mjs";
+import { readSessionModelFromStdin, resolveAutoUpdatePlan, resolveLazyCodexUpdatePlan, runAutoUpdateCheck } from "../scripts/auto-update.mjs";
 import { detectInstallFlow } from "../scripts/install-flow.mjs";
 import { resolveSpawnInvocation } from "../scripts/spawn-command.mjs";
 
@@ -20,6 +21,12 @@ function autoUpdateEnv(root, extra = {}) {
 	};
 }
 
+function stdinFrom(payload) {
+	const stream = new PassThrough();
+	stream.end(payload);
+	return stream;
+}
+
 test("#given auto update is disabled #when resolving plan #then no command is scheduled", () => {
 	const plan = resolveAutoUpdatePlan({
 		env: { LAZYCODEX_AUTO_UPDATE_DISABLED: "1" },
@@ -31,6 +38,33 @@ test("#given auto update is disabled #when resolving plan #then no command is sc
 	assert.equal(plan.reason, "disabled");
 });
 
+test("#given SessionStart payload with model #when reading stdin #then returns the model", async () => {
+	const payload = JSON.stringify({
+		hook_event_name: "SessionStart",
+		session_id: "s-1",
+		cwd: "/tmp",
+		model: "gpt-5.6-terra",
+		permission_mode: "default",
+		source: "startup",
+	});
+
+	assert.equal(await readSessionModelFromStdin(stdinFrom(payload)), "gpt-5.6-terra");
+});
+
+test("#given empty or malformed stdin #when reading session model #then returns null", async () => {
+	assert.equal(await readSessionModelFromStdin(stdinFrom("")), null);
+	assert.equal(await readSessionModelFromStdin(stdinFrom("not json")), null);
+	assert.equal(await readSessionModelFromStdin(stdinFrom(JSON.stringify({ model: "  " }))), null);
+	assert.equal(await readSessionModelFromStdin(stdinFrom(JSON.stringify({ session_id: "s-1" }))), null);
+	assert.equal(await readSessionModelFromStdin(null), null);
+});
+
+test("#given a TTY stdin #when reading session model #then returns null without waiting", async () => {
+	const stream = stdinFrom("{}");
+	stream.isTTY = true;
+	assert.equal(await readSessionModelFromStdin(stream), null);
+});
+
 test("#given stale state #when resolving plan #then installer update command is scheduled", () => {
 	const plan = resolveAutoUpdatePlan({
 		env: { LAZYCODEX_CURRENT_VERSION: "1.0.0", LAZYCODEX_LATEST_VERSION: "1.0.1" },

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

@@ -493,7 +493,7 @@ test("#given multi_agent_v2 enabled #when forcing disable #then flips the flag t
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /enabled = false/);
 	assert.doesNotMatch(result, /enabled = true/);
@@ -510,7 +510,7 @@ test("#given no multi_agent_v2 section #when forcing disable #then appends a dis
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
 	assert.match(result, /plugins = true/);
@@ -525,7 +525,7 @@ test("#given multi_agent_v2 section without enabled key #when forcing disable #t
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
 	assert.match(result, /max_concurrent_threads_per_session = 10000/);
@@ -541,7 +541,7 @@ test("#given [features] boolean shorthand multi_agent_v2 = true #when forcing di
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.doesNotMatch(result, /^multi_agent_v2\s*=/m);
 	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
@@ -557,7 +557,7 @@ test("#given multi_agent_v2 enabled #when forcing disable #then annotates the ma
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /openai\/codex#26753/);
 	assert.match(result, /LAZYCODEX_CONFIG_MIGRATION_DISABLED=1/);
@@ -567,7 +567,7 @@ test("#given multi_agent_v2 enabled #when forcing disable #then annotates the ma
 test("#given no multi_agent_v2 section #when forcing disable #then annotates the appended section", () => {
 	const config = ['model = "gpt-5.5"', ""].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /openai\/codex#26753/);
 	assert.match(result, /^#[^\n]*\n(?:#[^\n]*\n)*\[features\.multi_agent_v2\]\nenabled = false\n/m);
@@ -576,8 +576,8 @@ test("#given no multi_agent_v2 section #when forcing disable #then annotates the
 test("#given an annotated managed section #when forcing disable runs again #then does not duplicate the comment", () => {
 	const config = ['model = "gpt-5.5"', "", "[features.multi_agent_v2]", "enabled = true", ""].join("\n");
 
-	const annotated = forceDisableMultiAgentV2(config);
-	const rerun = forceDisableMultiAgentV2(`${annotated.replace("enabled = false", "enabled = true")}`);
+	const annotated = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
+	const rerun = forceDisableMultiAgentV2(`${annotated.replace("enabled = false", "enabled = true")}`, { multiAgentVersion: null });
 
 	const markers = rerun.match(/openai\/codex#26753/g) ?? [];
 	assert.equal(markers.length, 1);
@@ -594,7 +594,7 @@ test("#given [features] boolean shorthand multi_agent_v2 = false #when forcing d
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 	const parsed = parseTomlWithPython(result);
 
 	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
@@ -614,7 +614,7 @@ test("#given multi_agent_v2 already disabled #when forcing disable #then returns
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.equal(result, config);
 });
@@ -756,7 +756,7 @@ test("#given global config with forced multi_agent_v2 #when full migration runs
 test("#given enabled = true with an inline comment #when forcing disable #then flips to false and preserves the comment", () => {
 	const config = ["[features.multi_agent_v2]", "enabled = true # tuned by me", ""].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /^enabled = false # tuned by me$/m);
 	assert.doesNotMatch(result, /enabled = true/);
@@ -767,7 +767,7 @@ test("#given enabled = true with an inline comment #when forcing disable #then f
 test("#given a section header with an inline comment #when forcing disable #then patches in place without duplicating the table", () => {
 	const config = ["[features.multi_agent_v2] # pinned by me", "enabled = true", ""].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
 	assert.match(result, /enabled = false/);
@@ -779,19 +779,19 @@ test("#given an already-guarded commented config #when re-running #then output i
 	const configA = ["[features.multi_agent_v2]", "enabled = true # tuned by me", ""].join("\n");
 	const configB = ["[features.multi_agent_v2] # pinned by me", "enabled = true", ""].join("\n");
 
-	const firstA = forceDisableMultiAgentV2(configA);
-	const rerunA = forceDisableMultiAgentV2(firstA);
+	const firstA = forceDisableMultiAgentV2(configA, { multiAgentVersion: null });
+	const rerunA = forceDisableMultiAgentV2(firstA, { multiAgentVersion: null });
 	assert.equal(rerunA, firstA);
 
-	const firstB = forceDisableMultiAgentV2(configB);
-	const rerunB = forceDisableMultiAgentV2(firstB);
+	const firstB = forceDisableMultiAgentV2(configB, { multiAgentVersion: null });
+	const rerunB = forceDisableMultiAgentV2(firstB, { multiAgentVersion: null });
 	assert.equal(rerunB, firstB);
 });
 
 test("#given user-disabled with an inline comment #when forcing disable #then returns config unchanged", () => {
 	const config = ["[features.multi_agent_v2]", "enabled = false # I turned this off myself", ""].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.equal(result, config);
 });
@@ -799,7 +799,7 @@ test("#given user-disabled with an inline comment #when forcing disable #then re
 test("#given [features] shorthand true with an inline comment #when forcing disable #then removes the shorthand and appends one disabled table", () => {
 	const config = ["[features]", "plugins = true", "multi_agent_v2 = true # legacy", ""].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
 	assert.equal((result.match(/\[features\.multi_agent_v2\]/g) ?? []).length, 1);
@@ -816,12 +816,268 @@ test("#given a following section header with an inline comment #when inserting e
 		"",
 	].join("\n");
 
-	const result = forceDisableMultiAgentV2(config);
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: null });
 
 	assert.match(result, /\[features\.multi_agent_v2\]\nenabled = false\n/);
 	assert.match(result, /\[mcp_servers\.x\][^\n]*\nenabled = true/);
 });
 
+test("#given gpt-5.6-terra with managed disable #when model catalog prefers v2 #then clears enabled=false and managed comments", () => {
+	const config = [
+		'model = "gpt-5.6-terra"',
+		"",
+		"# Managed by LazyCodex: multi_agent_v2 is re-disabled on every Codex session start",
+		"# because enabling it fails every turn with HTTP 400 (openai/codex#26753).",
+		"# Opt out: LAZYCODEX_CONFIG_MIGRATION_DISABLED=1 (or OMO_CODEX_CONFIG_MIGRATION_DISABLED=1).",
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = false",
+		"max_concurrent_threads_per_session = 1000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: "v2" });
+
+	assert.doesNotMatch(result, /^\s*enabled\s*=\s*false/m);
+	assert.doesNotMatch(result, /openai\/codex#26753/);
+	assert.doesNotMatch(result, /Managed by LazyCodex: multi_agent_v2/);
+	assert.match(result, /\[features\.multi_agent_v2\]/);
+	assert.match(result, /max_concurrent_threads_per_session = 1000/);
+});
+
+test("#given gpt-5.6 v2 model with hide_spawn_agent_metadata=false #when clearing #then removes the stale metadata override", () => {
+	const config = [
+		'model = "gpt-5.6-sol"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = false",
+		"hide_spawn_agent_metadata = false",
+		"max_concurrent_threads_per_session = 1000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: "v2" });
+
+	assert.doesNotMatch(result, /^\s*enabled\s*=\s*false/m);
+	assert.doesNotMatch(result, /^\s*hide_spawn_agent_metadata\s*=/m);
+	assert.match(result, /max_concurrent_threads_per_session = 1000/);
+});
+
+test("#given gpt-5.6 v2 model with hide_spawn_agent_metadata=true #when clearing #then leaves the default-matching value alone", () => {
+	const config = [
+		'model = "gpt-5.6-sol"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = false",
+		"hide_spawn_agent_metadata = true",
+		"max_concurrent_threads_per_session = 1000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: "v2" });
+
+	assert.doesNotMatch(result, /^\s*enabled\s*=\s*false/m);
+	assert.match(result, /hide_spawn_agent_metadata = true/);
+});
+
+test("#given v1 model with hide_spawn_agent_metadata=false #when forcing disable #then keeps the metadata override", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features.multi_agent_v2]",
+		"hide_spawn_agent_metadata = false",
+		"max_concurrent_threads_per_session = 1000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: "v1" });
+
+	assert.match(result, /hide_spawn_agent_metadata = false/);
+	assert.match(result, /enabled = false/);
+});
+
+test("#given gpt-5.6-sol with no multi_agent_v2 section #when model catalog prefers v2 #then does not append a disable", () => {
+	const config = ['model = "gpt-5.6-sol"', "", "[features]", "plugins = true", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, { multiAgentVersion: "v2" });
+
+	assert.doesNotMatch(result, /\[features\.multi_agent_v2\]/);
+	assert.doesNotMatch(result, /enabled = false/);
+	assert.match(result, /plugins = true/);
+});
+
+test("#given gpt-5.6-terra managed disable #when full migration sees models_cache v2 #then clears disable and drops agents.max_threads", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-multi-agent-v2-gpt56-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.6-terra"',
+			'model_reasoning_effort = "xhigh"',
+			"",
+			"# Managed by LazyCodex: multi_agent_v2 is re-disabled on every Codex session start",
+			"# because enabling it fails every turn with HTTP 400 (openai/codex#26753).",
+			"",
+			"[agents]",
+			"max_threads = 1000",
+			"max_depth = 2",
+			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"max_concurrent_threads_per_session = 1000",
+			"",
+		].join("\n"),
+	);
+	await writeFile(
+		join(codexHome, "models_cache.json"),
+		JSON.stringify({
+			models: [{ slug: "gpt-5.6-terra", multi_agent_version: "v2" }],
+		}),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+	});
+
+	assert.deepEqual(result.changed, [configPath]);
+	const content = await readFile(configPath, "utf8");
+	assert.doesNotMatch(content, /^\s*enabled\s*=\s*false/m);
+	assert.doesNotMatch(content, /openai\/codex#26753/);
+	assert.doesNotMatch(content, /^\s*max_threads\s*=/m);
+	assert.match(content, /max_depth = 2/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+});
+
+test("#given config default gpt-5.5 #when SessionStart model is gpt-5.6-terra #then prefers session model and clears disable", () => {
+	const config = [
+		'model = "gpt-5.5"',
+		"",
+		"[features.multi_agent_v2]",
+		"enabled = false",
+		"max_concurrent_threads_per_session = 1000",
+		"",
+	].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, {
+		sessionModel: "gpt-5.6-terra",
+		multiAgentVersion: "v2",
+	});
+
+	assert.doesNotMatch(result, /^\s*enabled\s*=\s*false/m);
+	assert.match(result, /max_concurrent_threads_per_session = 1000/);
+});
+
+test("#given SessionStart without model #when requireSessionModel is set #then skips legacy force-disable", () => {
+	const config = ['model = "gpt-5.5"', "", "[features]", "plugins = true", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, {
+		multiAgentVersion: null,
+		requireSessionModel: true,
+		sessionModel: null,
+	});
+
+	assert.equal(result, config);
+	assert.doesNotMatch(result, /\[features\.multi_agent_v2\]/);
+});
+
+test("#given legacy [features] shorthand #when requireSessionModel skips force-disable #then still removes the shorthand", () => {
+	const config = ['model = "gpt-5.5"', "", "[features]", "plugins = true", "multi_agent_v2 = true", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, {
+		multiAgentVersion: null,
+		requireSessionModel: true,
+		sessionModel: null,
+	});
+
+	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
+	assert.match(result, /plugins = true/);
+	assert.doesNotMatch(result, /\[features\.multi_agent_v2\]/);
+});
+
+test("#given legacy [features] shorthand #when session model has no catalog entry #then still removes the shorthand", () => {
+	const config = ['model = "gpt-5.5"', "", "[features]", "multi_agent_v2 = false", ""].join("\n");
+
+	const result = forceDisableMultiAgentV2(config, {
+		multiAgentVersion: null,
+		sessionModel: "gpt-5.7-nova",
+	});
+
+	assert.doesNotMatch(result, /^\s*multi_agent_v2\s*=/m);
+	assert.doesNotMatch(result, /\[features\.multi_agent_v2\]/);
+});
+
+test("#given legacy shorthand and no session model on hook path #when full migration runs #then output stays valid TOML", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-multi-agent-v2-shorthand-hook-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		['model = "gpt-5.5"', 'model_reasoning_effort = "high"', "", "[features]", "plugins = true", "multi_agent_v2 = true", ""].join("\n"),
+	);
+
+	await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+		sessionModel: null,
+		requireSessionModel: true,
+	});
+
+	const content = await readFile(configPath, "utf8");
+	const parsed = parseTomlWithPython(content);
+	assert.doesNotMatch(content, /^\s*multi_agent_v2\s*=\s*(?:true|false)/m);
+	assert.equal(parsed.features.plugins, true);
+	assert.equal(parsed.features.multi_agent_v2.max_concurrent_threads_per_session, 1000);
+	assert.equal("enabled" in parsed.features.multi_agent_v2, false);
+});
+
+test("#given config default gpt-5.5 #when full migration gets SessionStart gpt-5.6-terra #then clears disable using session model", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-multi-agent-v2-session-model-"));
+	const codexHome = join(root, "codex-home");
+	await mkdir(codexHome, { recursive: true });
+	const configPath = join(codexHome, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.5"',
+			'model_reasoning_effort = "high"',
+			"",
+			"[agents]",
+			"max_threads = 1000",
+			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"max_concurrent_threads_per_session = 1000",
+			"",
+		].join("\n"),
+	);
+	await writeFile(
+		join(codexHome, "models_cache.json"),
+		JSON.stringify({
+			models: [
+				{ slug: "gpt-5.5", multi_agent_version: "v1" },
+				{ slug: "gpt-5.6-terra", multi_agent_version: "v2" },
+			],
+		}),
+	);
+
+	const result = await migrateCodexConfig({
+		env: { CODEX_HOME: codexHome, LAZYCODEX_MODEL_CATALOG_STATE_PATH: join(root, "model-state.json") },
+		cwd: root,
+		sessionModel: "gpt-5.6-terra",
+		requireSessionModel: true,
+	});
+
+	assert.deepEqual(result.changed, [configPath]);
+	const content = await readFile(configPath, "utf8");
+	assert.doesNotMatch(content, /^\s*enabled\s*=\s*false/m);
+	assert.doesNotMatch(content, /^\s*max_threads\s*=/m);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+});
+
 async function canCreateSymlink(type) {
 	const root = await mkdtemp(join(tmpdir(), "lazycodex-symlink-capability-"));
 	const target = join(root, "target");

package/packages/omo-codex/plugin/test/subagent-limit-migration.test.mjs

@@ -42,3 +42,36 @@ test("#given SessionStart config migration sees a low subagent cap #when migrati
 	assert.match(content, /max_concurrent_threads_per_session = 1000/);
 	assert.doesNotMatch(content, /^max_threads\s*=\s*6$/m);
 });
+
+test("#given gpt-5.6 session model with no models_cache #when migrating #then does not write agents.max_threads", async () => {
+	const root = await mkdtemp(join(tmpdir(), "lazycodex-subagent-limit-gpt56-nocache-"));
+	const configPath = join(root, "config.toml");
+	await writeFile(
+		configPath,
+		[
+			'model = "gpt-5.6-sol"',
+			'model_reasoning_effort = "xhigh"',
+			"",
+			"[agents]",
+			"max_threads = 1000",
+			"max_depth = 4",
+			"",
+			"[features.multi_agent_v2]",
+			"enabled = false",
+			"max_concurrent_threads_per_session = 1000",
+			"",
+		].join("\n"),
+	);
+
+	const result = await migrateConfigFile(configPath, {
+		env: { CODEX_HOME: root },
+		sessionModel: "gpt-5.6-sol",
+	});
+
+	const content = await readFile(configPath, "utf8");
+	assert.equal(result.changed, true);
+	assert.doesNotMatch(content, /^\s*max_threads\s*=/m);
+	assert.doesNotMatch(content, /^\s*enabled\s*=\s*false/m);
+	assert.match(content, /max_depth = 4/);
+	assert.match(content, /max_concurrent_threads_per_session = 1000/);
+});

package/packages/omo-codex/plugin/test/sync-skills-orchestration.test.mjs

@@ -29,7 +29,7 @@ function patternFromParts(parts, flags) {
 }
 
 const multiAgentV2RoleGuidance =
-	"On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`.";
+	"If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example:";
 const loadSkillsGuidance =
 	"When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`.";
 
@@ -148,7 +148,9 @@ call_omo_agent(subagent_type="explore", prompt="inspect")
 	assert.match(adapted, /fork_context":false/);
 	assert.match(adapted, /"agent_type":"explorer"/);
 	assert.match(adapted, /multi_agent_v1\.wait_agent/);
-	assert.doesNotMatch(adapted, /task_name/);
+	assert.match(adapted, /"task_name":"<lowercase_digits_underscores>"/);
+	assert.match(adapted, /fork_turns/);
+	assert.doesNotMatch(adapted, /\| `spawn_agent\({"task_name"/);
 	assert.doesNotMatch(adapted, /Obsolete generated compatibility prose/);
 });
 

package/packages/shared-skills/skills/review-work/SKILL.md

@@ -16,7 +16,9 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `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` |
 
-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. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. 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.
+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.
+
+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.
 
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 

package/packages/shared-skills/skills/start-work/SKILL.md

@@ -20,6 +20,8 @@ Translate any OpenCode-only tool name in an inherited example to its Codex equiv
 
 When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. 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.
+
 ## Codex Subagent Reliability
 
 Every `multi_agent_v1.spawn_agent` message is a self-contained executable assignment: `TASK: <imperative assignment>`, then `DELIVERABLE`, `SCOPE`, and `VERIFY`, with role instructions inside `message`. Use `fork_context: false` unless full history is truly required; paste only the context the child needs.

package/packages/shared-skills/skills/ulw-research/SKILL.md

@@ -17,7 +17,9 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 | `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` |
 
-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. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. 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.
+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.
+
+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.
 
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.