Remove legacy Claude Codex subagents surfaces

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: xuio

dist/index.js

@@ -26436,8 +26436,8 @@ var usageGuide = [
   "- Use codex_task_group when the work can be split into independent concurrent Codex tasks and Claude wants one combined response with rolled-up per-task findings.",
   "- Use codex_followup when Claude already has a session_id from codex_task or codex_task_group and wants to continue, steer, wait on, or cancel that same Codex context. This is a Codex-specific multi-turn extension; wait/cancel correspond to native TaskOutput/TaskStop-style operations.",
   "- Set codex_task background true for long-running work so Claude gets a session_id immediately, then use codex_wait_any for several sessions or codex_followup mode wait, steer, or cancel for one session.",
-  "- Subscribe to or read codex://sessions/{session_id} for background progress milestones and completion state. This is the Codex TaskGet/TaskList-style resource surface. The server emits notifications/resources/updated when meaningful Codex output changes.",
-  "- Diagnostics are resources by default: read codex://status, codex://doctor, or codex://usage when a prior call failed or availability is uncertain.",
+  "- Prefer codex_followup mode wait and codex_wait_any for completion. Subscribe to or read codex://sessions/{session_id} only when resource access is available and Claude needs progress milestones or completion state.",
+  "- Diagnostics are resources by default: read codex://status, codex://doctor, or codex://usage when a prior call failed or availability is uncertain. If Claude asks for a resource server id, use plugin:codex-subagents:codex-subagents, not the mcp__... tool prefix or a stale plain codex-subagents server.",
   "- Debug tools such as codex_status, codex_doctor, codex_usage_guide, codex_choose_tool, and codex_export_debug_bundle are hidden unless CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1.",
   "- Legacy/manual tools such as ask_codex, run_agent, run_agents, and old session names are hidden unless CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1.",
   "",

scripts/link-claude-dev-plugin.mjs

@@ -1,4 +1,4 @@
-import { lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { copyFile, lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,7 +11,12 @@ const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
 const marketplace = "codex-subagents-local";
 const pluginName = manifest.name;
 const version = manifest.version;
+const backupStamp = new Date().toISOString().replace(/[-:TZ.]/g, "").slice(0, 14);
 const installedPluginsPath = path.join(claudeHome, "plugins", "installed_plugins.json");
+const backupRoot = path.join(claudeHome, "backups", `codex-subagents-legacy-${backupStamp}`);
+const desktopConfigPath =
+  process.env.CLAUDE_DESKTOP_CONFIG ??
+  path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
 const marketplacePluginPath = path.join(
   claudeHome,
   "plugins",
@@ -48,8 +53,7 @@ async function resolvedPath(targetPath) {
 }
 
 function backupPath(targetPath) {
-  const stamp = new Date().toISOString().replace(/[-:TZ.]/g, "").slice(0, 14);
-  return `${targetPath}.backup-${stamp}`;
+  return `${targetPath}.backup-${backupStamp}`;
 }
 
 async function replaceWithSymlink(linkPath, targetPath) {
@@ -112,12 +116,70 @@ async function ensureInstalledPluginsEntry() {
   return entry;
 }
 
+function legacyBackupName(targetPath) {
+  return targetPath
+    .slice(claudeHome.length)
+    .replace(/^[/\\]+/, "")
+    .replace(/[/:\\]+/g, "__");
+}
+
+async function moveLegacyPath(targetPath) {
+  assertSafePath(targetPath);
+  if (!(await pathExists(targetPath))) return false;
+  if (dryRun) return true;
+
+  await mkdir(backupRoot, { recursive: true });
+  await rename(targetPath, path.join(backupRoot, `${legacyBackupName(targetPath)}.old`));
+  return true;
+}
+
+async function removeLegacyClaudeDesktopServer() {
+  if (!(await pathExists(desktopConfigPath))) return false;
+
+  const data = JSON.parse(await readFile(desktopConfigPath, "utf8"));
+  const serverConfig = data.mcpServers?.[pluginName];
+  if (!serverConfig) return false;
+
+  const command = typeof serverConfig.command === "string" ? serverConfig.command : "";
+  const isLegacyCodexSubagents =
+    command === path.join(root, "dist", "index.js") ||
+    command.endsWith("/claude-code-codex-subagents/dist/index.js") ||
+    command.includes("codex-subagents");
+  if (!isLegacyCodexSubagents) return false;
+
+  if (!dryRun) {
+    await mkdir(backupRoot, { recursive: true });
+    await copyFile(desktopConfigPath, path.join(backupRoot, "claude_desktop_config.json.before"));
+    delete data.mcpServers[pluginName];
+    await writeFile(desktopConfigPath, `${JSON.stringify(data, null, 2)}\n`);
+  }
+  return true;
+}
+
+async function cleanupLegacyInstallSurfaces() {
+  const removed = [];
+  for (const targetPath of [
+    path.join(claudeHome, "plugins", pluginName),
+    path.join(claudeHome, "commands", `${pluginName}.md`),
+    path.join(claudeHome, "plugins", "data", `${pluginName}-inline`),
+  ]) {
+    if (await moveLegacyPath(targetPath)) removed.push(targetPath);
+  }
+  if (await removeLegacyClaudeDesktopServer()) removed.push(desktopConfigPath);
+  return removed;
+}
+
 const marketplaceLink = await replaceWithSymlink(marketplacePluginPath, root);
 const cacheLink = await replaceWithSymlink(installPath, root);
 const entry = await ensureInstalledPluginsEntry();
+const removedLegacyPaths = await cleanupLegacyInstallSurfaces();
 
 console.log(`Marketplace plugin path: ${marketplaceLink.path} -> ${root}`);
 console.log(`Installed plugin path: ${cacheLink.path} -> ${root}`);
 console.log(`Installed plugin entry: ${entry.installPath}`);
+if (removedLegacyPaths.length > 0) {
+  console.log(`Removed legacy Codex subagents install surfaces: ${removedLegacyPaths.join(", ")}`);
+  if (!dryRun) console.log(`Legacy backups: ${backupRoot}`);
+}
 if (dryRun) console.log("Dry run only; no Claude plugin files were modified.");
 console.log("Claude Code CLI and Claude Desktop CLI share this ~/.claude plugin install.");

skills/codex-subagents/SKILL.md

@@ -28,7 +28,7 @@ Prefer the native Claude-like tools for normal use:
 - For independent tasks that can run concurrently, call `codex_task_group` with one task object per workstream. Split by ownership such as API flow, tests, security, performance, UI, docs, or migration risk. Keep tasks concrete and bounded, and set `max_parallel` to the smaller of the useful agent count and `4` unless the user asks for more.
 - For multi-turn Codex work, call `codex_task` for the initial prompt and preserve the returned `session_id`. Use `codex_followup` with `mode: "queue"` for ordinary follow-ups, `mode: "wait"` when Claude needs completion, and `mode: "steer"` for active redirection.
 - Use `codex_followup` mode `steer` only when the user wants to redirect active work now. It delivers real live steering with Codex `turn/steer` when app-server support is active. Set `interrupt_current: true` only when the active turn should be cancelled and redirected.
-- If unsure which path fits, read `codex://usage` before delegating.
+- If unsure which path fits, call `codex_task` or `codex_followup` first; use MCP resources only for diagnostics or when a tool response explicitly says to inspect a resource.
 
 Legacy tools such as `ask_codex`, `run_agent`, and old session names are hidden by default. They are exposed only when `CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1` is set for older clients. Tool-callable diagnostics are hidden unless `CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1`; use resources `codex://status`, `codex://doctor`, and `codex://usage` for normal diagnostics.
 
@@ -56,6 +56,8 @@ Do not use Codex for simple file reads, simple grep/search, or tiny local comman
 
 Read `codex://doctor` or `codex://status` only when diagnosing installation, binary resolution, defaults, or after a failed Codex tool call. Normal delegation should start with `codex_task`, `codex_task_group`, or `codex_followup`.
 
+When using Claude's generic `ReadMcpResourceTool`, the server id for this plugin is `plugin:codex-subagents:codex-subagents`. Do not convert the tool prefix `mcp__plugin_codex-subagents_codex-subagents__...` into `plugin_codex-subagents_codex-subagents`; that underscore form is not a server id. Do not use a plain `codex-subagents` server id if Claude also lists the plugin server, because that indicates a stale direct MCP entry and session resources will not line up with plugin tool calls.
+
 Example `codex_task` arguments for a retained session:
 
 ```json

src/index.ts

@@ -73,8 +73,8 @@ const usageGuide = [
   "- Use codex_task_group when the work can be split into independent concurrent Codex tasks and Claude wants one combined response with rolled-up per-task findings.",
   "- Use codex_followup when Claude already has a session_id from codex_task or codex_task_group and wants to continue, steer, wait on, or cancel that same Codex context. This is a Codex-specific multi-turn extension; wait/cancel correspond to native TaskOutput/TaskStop-style operations.",
   "- Set codex_task background true for long-running work so Claude gets a session_id immediately, then use codex_wait_any for several sessions or codex_followup mode wait, steer, or cancel for one session.",
-  "- Subscribe to or read codex://sessions/{session_id} for background progress milestones and completion state. This is the Codex TaskGet/TaskList-style resource surface. The server emits notifications/resources/updated when meaningful Codex output changes.",
-  "- Diagnostics are resources by default: read codex://status, codex://doctor, or codex://usage when a prior call failed or availability is uncertain.",
+  "- Prefer codex_followup mode wait and codex_wait_any for completion. Subscribe to or read codex://sessions/{session_id} only when resource access is available and Claude needs progress milestones or completion state.",
+  "- Diagnostics are resources by default: read codex://status, codex://doctor, or codex://usage when a prior call failed or availability is uncertain. If Claude asks for a resource server id, use plugin:codex-subagents:codex-subagents, not the mcp__... tool prefix or a stale plain codex-subagents server.",
   "- Debug tools such as codex_status, codex_doctor, codex_usage_guide, codex_choose_tool, and codex_export_debug_bundle are hidden unless CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1.",
   "- Legacy/manual tools such as ask_codex, run_agent, run_agents, and old session names are hidden unless CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1.",
   "",

test/dev-link.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { lstat, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
@@ -16,6 +16,7 @@ const installPath = path.join(
   claudeHome,
   `plugins/cache/codex-subagents-local/codex-subagents/${manifest.version}`,
 );
+const desktopConfigPath = path.join(claudeHome, "Claude", "claude_desktop_config.json");
 const marketplacePath = path.join(
   claudeHome,
   "plugins/marketplaces/codex-subagents-local/plugins/codex-subagents",
@@ -39,13 +40,32 @@ try {
     env: {
       ...process.env,
       CLAUDE_HOME: claudeHome,
+      CLAUDE_DESKTOP_CONFIG: desktopConfigPath,
     },
   });
   const dryRunOutput = [dryRun.stdout, dryRun.stderr].filter(Boolean).join("");
   assert(dryRun.status === 0, "dev link dry run should succeed", dryRunOutput);
   assert(dryRunOutput.includes("Dry run only"), "dry run should be explicit", dryRunOutput);
   assert(!(await pathExists(path.join(claudeHome, "plugins"))), "dry run should not create plugin directories", dryRunOutput);
 
+  await mkdir(path.dirname(desktopConfigPath), { recursive: true });
+  await writeFile(
+    desktopConfigPath,
+    `${JSON.stringify({
+      mcpServers: {
+        "codex-subagents": {
+          command: path.join(root, "dist", "index.js"),
+          args: [],
+          env: {},
+        },
+        unrelated: { command: "/bin/echo" },
+      },
+    }, null, 2)}\n`,
+  );
+  await mkdir(path.join(claudeHome, "plugins", "data", "codex-subagents-inline"), { recursive: true });
+  await mkdir(path.join(claudeHome, "commands"), { recursive: true });
+  await writeFile(path.join(claudeHome, "commands", "codex-subagents.md"), "legacy command\n");
+
   for (const pass of [1, 2]) {
     const result = spawnSync("node", ["scripts/link-claude-dev-plugin.mjs"], {
       cwd: root,
@@ -54,6 +74,7 @@ try {
       env: {
         ...process.env,
         CLAUDE_HOME: claudeHome,
+        CLAUDE_DESKTOP_CONFIG: desktopConfigPath,
       },
     });
 
@@ -67,6 +88,9 @@ try {
       marketplacePath,
       output,
     });
+    if (pass === 1) {
+      assert(output.includes("Removed legacy Codex subagents install surfaces"), "legacy cleanup should be reported", output);
+    }
   }
 
   const installed = JSON.parse(
@@ -76,6 +100,15 @@ try {
   assert(entry?.installPath === installPath, "installed plugin entry should use the cache symlink", entry);
   assert(entry?.gitCommitSha === "dev-symlink", "installed plugin entry should be marked as dev symlink", entry);
 
+  const desktopConfig = JSON.parse(await readFile(desktopConfigPath, "utf8"));
+  assert(!desktopConfig.mcpServers["codex-subagents"], "direct Claude Desktop MCP server should be removed", desktopConfig);
+  assert(desktopConfig.mcpServers.unrelated, "unrelated Claude Desktop MCP servers should be preserved", desktopConfig);
+  assert(!(await pathExists(path.join(claudeHome, "commands", "codex-subagents.md"))), "legacy command should be moved out of active Claude paths");
+  assert(
+    !(await pathExists(path.join(claudeHome, "plugins", "data", "codex-subagents-inline"))),
+    "legacy inline plugin data should be moved out of active Claude paths",
+  );
+
   console.log("Claude dev-link test passed");
 } finally {
   await rm(claudeHome, { recursive: true, force: true });