fix(pi): avoid subagent tool conflicts

Author: dragosdm

src/converters/claude-to-pi.ts

@@ -1,5 +1,5 @@
 import { formatFrontmatter } from "../utils/frontmatter"
-import { normalizePiSkillName, uniquePiSkillName } from "../utils/pi-skills"
+import { normalizePiSkillName, transformPiBodyContent, uniquePiSkillName } from "../utils/pi-skills"
 import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
 import type {
   PiBundle,
@@ -49,14 +49,13 @@ export function convertClaudeToPi(
 }
 
 function convertPrompt(command: ClaudeCommand, usedNames: Set<string>) {
-  const name = uniqueName(normalizeName(command.name), usedNames)
+  const name = uniquePiSkillName(normalizePiSkillName(command.name), usedNames)
   const frontmatter: Record<string, unknown> = {
     description: command.description,
     "argument-hint": command.argumentHint,
   }
 
-  let body = transformContentForPi(command.body)
-  body = appendCompatibilityNoteIfNeeded(body)
+  const body = transformPiBodyContent(command.body)
 
   return {
     name,
@@ -80,74 +79,19 @@ function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSk
     sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
   }
 
-  const body = [
+  const body = transformPiBodyContent([
     ...sections,
     agent.body.trim().length > 0
       ? agent.body.trim()
       : `Instructions converted from the ${agent.name} agent.`,
-  ].join("\n\n")
+  ].join("\n\n"))
 
   return {
     name,
     content: formatFrontmatter(frontmatter, body),
   }
 }
 
-function transformContentForPi(body: string): string {
-  let result = body
-
-  // Task repo-research-analyst(feature_description)
-  // -> Run subagent with agent="repo-research-analyst" and task="feature_description"
-  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
-  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
-    const skillName = normalizeName(agentName)
-    const trimmedArgs = args.trim().replace(/\s+/g, " ")
-    return `${prefix}Run subagent with agent=\"${skillName}\" and task=\"${trimmedArgs}\".`
-  })
-
-  // Claude-specific tool references
-  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
-  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
-  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
-
-  // /command-name or /workflows:command-name -> /workflows-command-name
-  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
-  result = result.replace(slashCommandPattern, (match, commandName: string) => {
-    if (commandName.includes("/")) return match
-    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
-      return match
-    }
-
-    if (commandName.startsWith("skill:")) {
-      const skillName = commandName.slice("skill:".length)
-      return `/skill:${normalizePiSkillName(skillName)}`
-    }
-
-    const withoutPrefix = commandName.startsWith("prompts:")
-      ? commandName.slice("prompts:".length)
-      : commandName
-
-    return `/${normalizeName(withoutPrefix)}`
-  })
-
-  return result
-}
-
-function appendCompatibilityNoteIfNeeded(body: string): string {
-  if (!/\bmcp\b/i.test(body)) return body
-
-  const note = [
-    "",
-    "## Pi + MCPorter note",
-    "For MCP access in Pi, use MCPorter via the generated tools:",
-    "- `mcporter_list` to inspect available MCP tools",
-    "- `mcporter_call` to invoke a tool",
-    "",
-  ].join("\n")
-
-  return body + note
-}
-
 function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcporterConfig {
   const mcpServers: Record<string, PiMcporterServer> = {}
 
@@ -173,36 +117,10 @@ function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcpor
   return { mcpServers }
 }
 
-function normalizeName(value: string): string {
-  const trimmed = value.trim()
-  if (!trimmed) return "item"
-  const normalized = trimmed
-    .toLowerCase()
-    .replace(/[\\/]+/g, "-")
-    .replace(/[:\s]+/g, "-")
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-+|-+$/g, "")
-  return normalized || "item"
-}
-
 function sanitizeDescription(value: string, maxLength = PI_DESCRIPTION_MAX_LENGTH): string {
   const normalized = value.replace(/\s+/g, " ").trim()
   if (normalized.length <= maxLength) return normalized
   const ellipsis = "..."
   return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
 }
 
-function uniqueName(base: string, used: Set<string>): string {
-  if (!used.has(base)) {
-    used.add(base)
-    return base
-  }
-  let index = 2
-  while (used.has(`${base}-${index}`)) {
-    index += 1
-  }
-  const name = `${base}-${index}`
-  used.add(name)
-  return name
-}

src/sync/pi-skills.ts

@@ -0,0 +1,32 @@
+import path from "path"
+import type { ClaudeSkill } from "../types/claude"
+import { ensureDir } from "../utils/files"
+import { copySkillDirForPi, normalizePiSkillName, skillFileMatchesPiTarget, uniquePiSkillName } from "../utils/pi-skills"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncPiSkills(
+  skills: ClaudeSkill[],
+  skillsDir: string,
+): Promise<void> {
+  await ensureDir(skillsDir)
+
+  const usedNames = new Set<string>()
+
+  for (const skill of skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with unsafe name: ${skill.name}`)
+      continue
+    }
+
+    const targetName = uniquePiSkillName(normalizePiSkillName(skill.name), usedNames)
+    const target = path.join(skillsDir, targetName)
+    const alreadyPiCompatible = await skillFileMatchesPiTarget(skill.skillPath, targetName)
+
+    if (skill.name === targetName && alreadyPiCompatible) {
+      await forceSymlink(skill.sourceDir, target)
+      continue
+    }
+
+    await copySkillDirForPi(skill.sourceDir, target, targetName)
+  }
+}

src/sync/pi.ts

@@ -4,7 +4,7 @@ import type { ClaudeMcpServer } from "../types/claude"
 import { ensureDir } from "../utils/files"
 import { syncPiCommands } from "./commands"
 import { mergeJsonConfigAtKey } from "./json-config"
-import { syncSkills } from "./skills"
+import { syncPiSkills } from "./pi-skills"
 
 type McporterServer = {
   baseUrl?: string
@@ -24,7 +24,7 @@ export async function syncToPi(
 ): Promise<void> {
   const mcporterPath = path.join(outputRoot, "compound-engineering", "mcporter.json")
 
-  await syncSkills(config.skills, path.join(outputRoot, "skills"))
+  await syncPiSkills(config.skills, path.join(outputRoot, "skills"))
   await syncPiCommands(config, outputRoot)
 
   if (Object.keys(config.mcpServers).length > 0) {

src/sync/skills.ts

@@ -1,6 +1,5 @@
 import path from "path"
 import type { ClaudeSkill } from "../types/claude"
-import { copySkillDirForPi, normalizePiSkillName, skillFrontmatterMatchesPiName, uniquePiSkillName } from "../utils/pi-skills"
 import { ensureDir } from "../utils/files"
 import { forceSymlink, isValidSkillName } from "../utils/symlink"
 
@@ -10,23 +9,13 @@ export async function syncSkills(
 ): Promise<void> {
   await ensureDir(skillsDir)
 
-  const usedNames = new Set<string>()
-
   for (const skill of skills) {
     if (!isValidSkillName(skill.name)) {
-      console.warn(`Skipping skill with unsafe name: ${skill.name}`)
-      continue
-    }
-
-    const targetName = uniquePiSkillName(normalizePiSkillName(skill.name), usedNames)
-    const target = path.join(skillsDir, targetName)
-    const frontmatterMatches = await skillFrontmatterMatchesPiName(skill.skillPath, targetName)
-
-    if (skill.name === targetName && frontmatterMatches) {
-      await forceSymlink(skill.sourceDir, target)
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
       continue
     }
 
-    await copySkillDirForPi(skill.sourceDir, target, targetName)
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
   }
 }

src/targets/pi.ts

@@ -18,8 +18,8 @@ const PI_AGENTS_BLOCK_BODY = `## Compound Engineering (Pi compatibility)
 This block is managed by compound-plugin.
 
 Compatibility notes:
-- Claude Task(agent, args) maps to the subagent extension tool
-- For parallel agent runs, batch multiple subagent calls with multi_tool_use.parallel
+- Claude Task(agent, args) maps to the ce_subagent extension tool
+- Use ce_subagent for Compound Engineering workflows even when another extension also provides a generic subagent tool
 - AskUserQuestion maps to the ask_user_question extension tool
 - MCP access uses MCPorter via mcporter_list and mcporter_call extension tools
 - MCPorter config path: .pi/compound-engineering/mcporter.json (project) or ~/.pi/agent/compound-engineering/mcporter.json (global)

src/templates/pi/compat-extension.ts

@@ -245,9 +245,9 @@ export default function (pi: ExtensionAPI) {
   })
 
   pi.registerTool({
-    name: "subagent",
-    label: "Subagent",
-    description: "Run one or more skill-based subagent tasks. Supports single, parallel, and chained execution.",
+    name: "ce_subagent",
+    label: "Compound Engineering Subagent",
+    description: "Run one or more Compound Engineering skill-based subagent tasks. Supports single, parallel, and chained execution.",
     parameters: Type.Object({
       agent: Type.Optional(Type.String({ description: "Single subagent name" })),
       task: Type.Optional(Type.String({ description: "Single subagent task" })),

src/utils/pi-skills.ts

@@ -1,7 +1,10 @@
+import { promises as fs } from "fs"
 import path from "path"
 import { copyDir, pathExists, readText, writeText } from "./files"
 import { formatFrontmatter, parseFrontmatter } from "./frontmatter"
 
+export const PI_CE_SUBAGENT_TOOL = "ce_subagent"
+
 export function normalizePiSkillName(value: string): string {
   const trimmed = value.trim()
   if (!trimmed) return "item"
@@ -37,22 +40,80 @@ export function uniquePiSkillName(base: string, used: Set<string>): string {
   return name
 }
 
-export async function skillFrontmatterMatchesPiName(skillPath: string, targetName: string): Promise<boolean> {
+export function transformPiBodyContent(body: string): string {
+  let result = body
+
+  const taskPattern = /^(\s*(?:(?:[-*])\s+|\d+\.\s+)?)Task\s+([a-z][a-z0-9:_-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const normalizedAgent = normalizePiTaskAgentName(agentName)
+    const trimmedArgs = args.trim().replace(/\s+/g, " ")
+    return `${prefix}Run ${PI_CE_SUBAGENT_TOOL} with agent="${normalizedAgent}" and task="${trimmedArgs}".`
+  })
+
+  result = result.replace(/\bRun subagent with\b/g, `Run ${PI_CE_SUBAGENT_TOOL} with`)
+  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
+  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
+  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
+
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
+      return match
+    }
+
+    if (commandName.startsWith("skill:")) {
+      const skillName = commandName.slice("skill:".length)
+      return `/skill:${normalizePiSkillName(skillName)}`
+    }
+
+    const withoutPrefix = commandName.startsWith("prompts:")
+      ? commandName.slice("prompts:".length)
+      : commandName
+
+    return `/${normalizePiSkillName(withoutPrefix)}`
+  })
+
+  return appendCompatibilityNoteIfNeeded(result)
+}
+
+export async function skillFileMatchesPiTarget(skillPath: string, targetName: string): Promise<boolean> {
   if (!(await pathExists(skillPath))) {
     return false
   }
 
   const raw = await readText(skillPath)
   const parsed = parseFrontmatter(raw)
-  return parsed.data.name === targetName
+  if (Object.keys(parsed.data).length === 0 && parsed.body === raw) {
+    return false
+  }
+
+  if (parsed.data.name !== targetName) {
+    return false
+  }
+
+  return transformPiBodyContent(parsed.body) === parsed.body
 }
 
-export async function copySkillDirForPi(sourceDir: string, targetDir: string, targetName: string): Promise<void> {
+export async function copySkillDirForPi(
+  sourceDir: string,
+  targetDir: string,
+  targetName: string,
+): Promise<void> {
+  if (await pathExists(targetDir)) {
+    const stats = await fs.lstat(targetDir)
+    if (stats.isSymbolicLink()) {
+      await fs.unlink(targetDir)
+    } else {
+      await fs.rm(targetDir, { recursive: true, force: true })
+    }
+  }
+
   await copyDir(sourceDir, targetDir)
-  await rewriteSkillFrontmatterForPi(path.join(targetDir, "SKILL.md"), targetName)
+  await rewriteSkillFileForPi(path.join(targetDir, "SKILL.md"), targetName)
 }
 
-export async function rewriteSkillFrontmatterForPi(skillPath: string, targetName: string): Promise<void> {
+export async function rewriteSkillFileForPi(skillPath: string, targetName: string): Promise<void> {
   if (!(await pathExists(skillPath))) {
     return
   }
@@ -63,8 +124,32 @@ export async function rewriteSkillFrontmatterForPi(skillPath: string, targetName
     return
   }
 
-  const updated = formatFrontmatter({ ...parsed.data, name: targetName }, parsed.body)
+  const updated = formatFrontmatter(
+    { ...parsed.data, name: targetName },
+    transformPiBodyContent(parsed.body),
+  )
+
   if (updated !== raw) {
     await writeText(skillPath, updated)
   }
 }
+
+function normalizePiTaskAgentName(value: string): string {
+  const leafName = value.split(":").filter(Boolean).pop() ?? value
+  return normalizePiSkillName(leafName)
+}
+
+function appendCompatibilityNoteIfNeeded(body: string): string {
+  if (!/\bmcp\b/i.test(body)) return body
+
+  const note = [
+    "",
+    "## Pi + MCPorter note",
+    "For MCP access in Pi, use MCPorter via the generated tools:",
+    "- `mcporter_list` to inspect available MCP tools",
+    "- `mcporter_call` to invoke a tool",
+    "",
+  ].join("\n")
+
+  return body + note
+}