npm - @softspark/ai-toolkit - Versions diffs - 4.14.0 → 4.15.0 - Mend

@softspark/ai-toolkit 4.14.0 → 4.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (48) hide show

package/CHANGELOG.md +35 -0
package/README.md +11 -10
package/app/.claude-plugin/plugin.json +1 -1
package/app/CLAUDE.md.template +3 -0
package/app/agents/fact-checker.md +1 -1
package/app/hooks/_search-capability.sh +3 -2
package/app/hooks/stop-search-check.sh +2 -1
package/benchmarks/ecosystem-doctor-snapshot.json +73 -31
package/kb/procedures/maintenance-sop.md +26 -13
package/kb/procedures/release-verification-sop.md +41 -36
package/kb/reference/architecture-overview.md +23 -7
package/kb/reference/codex-cli-compatibility.md +96 -36
package/kb/reference/extension-api.md +52 -9
package/kb/reference/global-install-model.md +53 -21
package/kb/reference/hooks-catalog.md +44 -8
package/kb/reference/mcp-editor-compatibility.md +27 -6
package/kb/reference/mcp-templates.md +12 -6
package/kb/reference/opencode-compatibility.md +13 -7
package/kb/reference/plugin-pack-conventions.md +7 -7
package/kb/reference/skills-catalog.md +3 -3
package/kb/reference/supported-tools-registry.md +19 -17
package/kb/reference/windows-support.md +26 -3
package/llms-full.txt +443 -180
package/llms.txt +1 -1
package/manifest.json +1 -1
package/package.json +2 -2
package/scripts/codex_skill_adapter.py +448 -198
package/scripts/dir_rules_shared.py +2 -11
package/scripts/ecosystem_tools.json +29 -8
package/scripts/emission.py +5 -91
package/scripts/generate_agents_md.py +4 -87
package/scripts/generate_codex.py +5 -95
package/scripts/generate_codex_agents.py +242 -0
package/scripts/generate_codex_hooks.py +648 -55
package/scripts/generate_codex_skills.py +15 -6
package/scripts/generate_copilot.py +771 -74
package/scripts/generate_copilot_hooks.py +606 -0
package/scripts/generate_cursor_hooks.py +453 -121
package/scripts/generate_opencode_commands.py +4 -6
package/scripts/inject_hook_cli.py +770 -205
package/scripts/injection.py +102 -23
package/scripts/install_steps/ai_tools.py +123 -83
package/scripts/instruction_core.py +95 -0
package/scripts/mcp_editors.py +934 -80
package/scripts/mcp_manager.py +46 -26
package/scripts/plugin.py +291 -114
package/scripts/secure_fs.py +538 -0
package/scripts/uninstall.py +1279 -208

package/scripts/codex_skill_adapter.py CHANGED Viewed

@@ -7,9 +7,12 @@ Codex subagents and plan tracking.
 """
 from __future__ import annotations
+import errno
+import json
+import os
 import re
-import shutil
 import sys
+import tempfile
 from pathlib import Path
 try:
@@ -25,45 +28,91 @@ CLAUDE_ONLY_TOOLS = frozenset({
     "Skill", "EnterPlanMode", "ExitPlanMode",
 })
-CODEX_DELEGATION_TOOLS = (
-    "spawn_agent", "send_input", "wait_agent", "close_agent", "update_plan",
-)
 ADAPTED_MARKER = ".ai-toolkit-codex-adapted"
 _FRONTMATTER_RE = re.compile(r"\A---\n(?P<frontmatter>.*?)\n---\n?(?P<body>.*)\Z", re.S)
-_SINGLE_AGENT_CALL_RE = re.compile(
-    r'Agent\(subagent_type="([^"]+)",\s*prompt="([^"]+)"[^)]*\)'
-)
-_MULTILINE_AGENT_CALL_RE = re.compile(
-    r'Agent\(\s*\n'
-    r'\s*subagent_type="([^"]+)"\s*,\s*\n'
-    r'\s*description="([^"]+)"\s*,\s*\n'
-    r'\s*prompt="([^"]+)"\s*\n'
-    r'\)',
-    re.S,
-)
-_CODEX_NOTE = """
-## Codex Translation Layer
-This generated Codex variant preserves the original workflow while translating
-Claude-only delegation primitives into Codex-native ones:
-- Use `spawn_agent(..., fork_context=True, ...)` instead of Claude `Agent(...)`.
-- Pick `explorer` for read-only discovery, `worker` for edits, `default` for
-  synthesis, planning, and mixed execution.
-- Use `send_input` to redirect or clarify an active subagent.
-- Use `wait_agent` only when the next critical-path step is blocked on a
-  delegated result.
-- Use `close_agent` after integrating finished subagents.
-- Track progress with `update_plan` or a local checklist instead of Claude
-  task/team APIs.
-- Treat a "team" as a coordinated set of spawned subagents with explicit file
-  ownership. No extra Codex feature flag is required.
+_AGENT_START_RE = re.compile(r"\bAgent\s*\(")
+_TASK_API_RE = re.compile(r"\bTask(?:Create|List|Update|Get|Output|Stop)\b")
+_POSITIONAL_ARGUMENT_RE = re.compile(r"\$([1-9])\b")
+_PLATFORM_LABELS = {"codex": "Codex", "opencode": "OpenCode"}
+_UNSUPPORTED_DIRECTORY_FSYNC_ERRNOS = frozenset({
+    errno.EBADF,
+    errno.EINVAL,
+    getattr(errno, "ENOTSUP", errno.EINVAL),
+    getattr(errno, "EOPNOTSUPP", errno.EINVAL),
+})
+_ADAPTATION_BODY_TOKENS = frozenset({
+    "$ARGUMENTS",
+    "CLAUDE_SKILL_DIR",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS",
+    "spawn_agent",
+    "send_input",
+    "wait_agent",
+    "close_agent",
+    "update_plan",
+    "fork_context",
+    "agent_type=",
+    "TeamCreate",
+    "TeamDelete",
+    "SendMessage",
+})
+def _translation_note(platform: str) -> str:
+    label = _PLATFORM_LABELS[platform]
+    return f"""
+## {label} Translation Layer
+This generated {label} variant preserves the workflow intent using durable,
+client-independent guidance:
+- Use {label}-native subagents to delegate independent work when parallelism
+  materially improves speed or quality.
+- Give each delegated task a narrow objective, relevant context, explicit file
+  ownership, and a clear expected result.
+- Use the subagent controls available in the current client to steer or stop
+  delegated work without assuming a particular tool signature.
+- Wait for delegated results only when the next critical-path step depends on
+  them, then integrate the results in the parent task.
+- Track progress using the planning mechanism available in the current client
+  or an explicit local checklist.
+- Treat a team as coordinated {label}-native subagents with non-overlapping work.
+- Resolve `./` paths in command examples from the installed skill directory
+  that contains this `SKILL.md` file.
 """
+def _semantic_replacements(platform: str) -> dict[str, str]:
+    label = _PLATFORM_LABELS[platform]
+    native_subagent = f"{label}-native subagent"
+    replacements = {
+        "${CLAUDE_SKILL_DIR}/": "./",
+        "$CLAUDE_SKILL_DIR/": "./",
+        "${CLAUDE_SKILL_DIR}": "the installed skill directory",
+        "CLAUDE_SKILL_DIR": "the installed skill directory",
+        "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": f"{label} subagent support",
+        "spawn_agent": f"delegate independent work to a {native_subagent}",
+        "send_input": "steer a running subagent",
+        "wait_agent": "wait for delegated results",
+        "close_agent": "stop or finish delegated work",
+        "update_plan": "the planning mechanism available in the current client",
+        "fork_context": "appropriate inherited task context",
+        "agent_type=": "a suitable subagent role",
+        "TeamCreate": f"coordinate {label}-native subagents",
+        "TeamDelete": "finish coordinated subagent work",
+        "SendMessage": "steer a running subagent",
+        "TaskCreate": "the available planning mechanism",
+        "TaskList": "the available planning mechanism",
+        "TaskUpdate": "the available planning mechanism",
+        "TaskGet": "review delegated progress",
+        "TaskOutput": "collect delegated results",
+        "TaskStop": "stop delegated work",
+    }
+    if platform == "codex":
+        replacements["$ARGUMENTS"] = "the user-supplied task details"
+    return replacements
 def skill_tools(skill_file: Path) -> list[str]:
     """Return ordered allowed-tools entries from a skill frontmatter block."""
     tools_str = frontmatter_field(skill_file, "allowed-tools") or ""
@@ -71,8 +120,16 @@ def skill_tools(skill_file: Path) -> list[str]:
 def is_codex_adapted_skill(skill_file: Path) -> bool:
-    """Return True if a skill needs Claude→Codex delegation adaptation."""
-    return bool(set(skill_tools(skill_file)) & CLAUDE_ONLY_TOOLS)
+    """Return True when a source skill needs portable client adaptation."""
+    if set(skill_tools(skill_file)) & CLAUDE_ONLY_TOOLS:
+        return True
+    text = skill_file.read_text(encoding="utf-8")
+    if any(token in text for token in _ADAPTATION_BODY_TOKENS):
+        return True
+    if _AGENT_START_RE.search(text) or _TASK_API_RE.search(text):
+        return True
+    is_user_invocable = frontmatter_field(skill_file, "user-invocable") != "false"
+    return is_user_invocable and bool(_POSITIONAL_ARGUMENT_RE.search(text))
 def codex_skill_description(skill_file: Path) -> str:
@@ -81,95 +138,343 @@ def codex_skill_description(skill_file: Path) -> str:
     if not description:
         return ""
     if is_codex_adapted_skill(skill_file):
-        return f"{description} Codex-adapted: uses native subagents and plan tracking."
+        return (
+            f"{description} Codex-adapted: uses Codex-native subagents and "
+            "current-client planning controls."
+        )
     return description
 def build_codex_skill_text(skill_file: Path) -> str:
     """Render the Codex-facing SKILL.md contents for a source skill."""
+    return _build_portable_skill_text(skill_file, "codex")
+def build_opencode_skill_text(skill_file: Path) -> str:
+    """Render an OpenCode-facing skill without leaking Codex branding."""
+    return _build_portable_skill_text(skill_file, "opencode")
+def _build_portable_skill_text(skill_file: Path, platform: str) -> str:
+    """Render a client-specific skill using semantic, signature-free guidance."""
+    if platform not in _PLATFORM_LABELS:
+        raise ValueError(f"Unsupported skill adaptation platform: {platform}")
     text = skill_file.read_text(encoding="utf-8")
     match = _FRONTMATTER_RE.match(text)
     if not match:
-        return text
+        return _adapt_body(text, platform) if is_codex_adapted_skill(skill_file) else text
-    frontmatter = _parse_frontmatter(match.group("frontmatter"))
     body = match.group("body")
     adapted = is_codex_adapted_skill(skill_file)
     if adapted:
-        frontmatter = _adapt_frontmatter(frontmatter)
-        body = _adapt_body(body)
+        body = _adapt_body(body, platform)
+        name = frontmatter_field(skill_file, "name")
+        description = (
+            codex_skill_description(skill_file)
+            if platform == "codex"
+            else frontmatter_field(skill_file, "description")
+        )
+        rendered_frontmatter = "\n".join(
+            (f"name: {name}", f"description: {json.dumps(description, ensure_ascii=False)}")
+        )
+    else:
+        frontmatter = _parse_frontmatter(match.group("frontmatter"))
+        rendered_frontmatter = _render_frontmatter(frontmatter)
-    rendered_frontmatter = _render_frontmatter(frontmatter)
     return f"---\n{rendered_frontmatter}\n---\n{body.rstrip()}\n"
 def sync_codex_skill(skill_dir: Path, skills_dst: Path) -> str:
     """Install one skill into `.agents/skills/` and return its mode."""
     skill_file = skill_dir / "SKILL.md"
-    target = skills_dst / skill_dir.name
     adapted = is_codex_adapted_skill(skill_file)
-    marker = target / ADAPTED_MARKER
     if adapted:
-        if target.is_symlink():
-            target.unlink()
-        elif target.is_dir() and not marker.is_file():
-            return "skipped"
-        elif target.is_dir():
-            shutil.rmtree(target)
-        elif target.exists():
-            return "skipped"
+        return _sync_adapted_skill(skill_dir, skills_dst)
+    return _sync_native_skill(skill_dir, skills_dst)
+def prepare_codex_skills_dir(target_dir: Path) -> Path:
+    """Create the documented Codex skill root without following symlinks."""
+    if target_dir.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Codex target directory: {target_dir}")
+    agents_dir = target_dir / ".agents"
+    skills_dst = agents_dir / "skills"
+    _assert_safe_skill_roots(agents_dir, skills_dst)
+    skills_dst.mkdir(parents=True, exist_ok=True)
+    _assert_safe_skill_roots(agents_dir, skills_dst)
+    return skills_dst
+def unmanaged_codex_skill_names(skills_dst: Path, skills_src: Path) -> set[str]:
+    """Return logical names declared by user-owned destination entries."""
+    names: set[str] = set()
+    for item in sorted(skills_dst.iterdir()):
+        if _is_managed_entry(item, skills_src):
+            continue
+        skill_file = item / "SKILL.md"
+        try:
+            name = frontmatter_field(skill_file, "name")
+        except (OSError, UnicodeError):
+            continue
+        if name:
+            names.add(name)
+    return names
+def cleanup_codex_skills(
+    skills_dst: Path,
+    skills_src: Path,
+    blocked_names: set[str] | None = None,
+) -> None:
+    """Remove stale or shadowed toolkit-managed entries without touching user data."""
+    _assert_safe_skill_roots(skills_dst.parent, skills_dst)
+    skills_src_resolved = skills_src.resolve()
+    blocked_names = blocked_names or set()
+    for item in skills_dst.iterdir():
+        src = skills_src / item.name
+        if item.name in blocked_names and _is_managed_entry(item, skills_src):
+            if item.is_symlink():
+                item.unlink()
+            else:
+                _remove_managed_wrapper(item, skills_src_resolved)
+            continue
+        if item.is_symlink():
+            target = _symlink_target(item)
+            if src.is_dir() and target == src.resolve():
+                continue
+            if _is_relative_to(target, skills_src_resolved):
+                item.unlink()
+                continue
+        if _is_adapted_wrapper(item) and not src.is_dir():
+            _remove_managed_wrapper(item, skills_src_resolved)
-        target.mkdir(parents=True, exist_ok=True)
-        marker.write_text("generated by ai-toolkit for Codex\n", encoding="utf-8")
-        for child in sorted(skill_dir.iterdir()):
-            dest = target / child.name
-            if child.name == "SKILL.md":
-                continue
-            if dest.is_symlink() or dest.is_file():
-                dest.unlink()
-            elif dest.is_dir():
-                shutil.rmtree(dest)
-            dest.symlink_to(child)
+def _assert_safe_skill_roots(agents_dir: Path, skills_dst: Path) -> None:
+    if agents_dir.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Codex agents directory: {agents_dir}")
+    if skills_dst.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Codex skills directory: {skills_dst}")
+def _symlink_target(path: Path) -> Path:
+    raw_target = Path(os.readlink(path))
+    if not raw_target.is_absolute():
+        raw_target = path.parent / raw_target
+    return raw_target.resolve(strict=False)
+def _points_to(path: Path, target: Path) -> bool:
+    return path.is_symlink() and _symlink_target(path) == target.resolve()
-        (target / "SKILL.md").write_text(build_codex_skill_text(skill_file), encoding="utf-8")
-        return "adapted"
+def _is_adapted_wrapper(path: Path) -> bool:
+    if path.is_symlink() or not path.is_dir():
+        return False
+    marker = path / ADAPTED_MARKER
+    return not marker.is_symlink() and marker.is_file()
+def _is_managed_entry(path: Path, skills_src: Path) -> bool:
+    if _is_adapted_wrapper(path):
+        return True
+    if not path.is_symlink():
+        return False
+    return _is_relative_to(_symlink_target(path), skills_src.resolve())
+def _sync_native_skill(skill_dir: Path, skills_dst: Path) -> str:
+    target = skills_dst / skill_dir.name
     if target.is_symlink():
-        if target.resolve() == skill_dir.resolve():
-            return "linked"
-        target.unlink()
-    elif target.is_dir():
-        if marker.is_file():
-            shutil.rmtree(target)
-        else:
+        return "linked" if _points_to(target, skill_dir) else "skipped"
+    if _is_adapted_wrapper(target):
+        if not _remove_managed_wrapper(target, skill_dir.parent.resolve()):
             return "skipped"
     elif target.exists():
         return "skipped"
     target.symlink_to(skill_dir)
     return "linked"
-def cleanup_codex_skills(skills_dst: Path, skills_src: Path) -> None:
-    """Remove broken symlinks and stale generated Codex skill wrappers."""
-    skills_src_resolved = skills_src.resolve()
-    for item in skills_dst.iterdir():
-        src = skills_src / item.name
-        if item.is_symlink():
-            if not item.exists():
-                item.unlink()
-                continue
-            target = item.resolve()
-            if src.is_dir() and target == src.resolve():
-                continue
-            if _is_relative_to(target, skills_src_resolved):
-                item.unlink()
+def _sync_adapted_skill(skill_dir: Path, skills_dst: Path) -> str:
+    target = skills_dst / skill_dir.name
+    if target.is_symlink():
+        if not _points_to(target, skill_dir):
+            return "skipped"
+        return _create_adapted_wrapper(skill_dir, target, replace_managed_link=True)
+    if target.exists() and not _is_adapted_wrapper(target):
+        return "skipped"
+    if not target.exists():
+        return _create_adapted_wrapper(skill_dir, target)
+    return _update_adapted_wrapper(skill_dir, target)
+def _create_adapted_wrapper(
+    skill_dir: Path,
+    target: Path,
+    *,
+    replace_managed_link: bool = False,
+) -> str:
+    """Build a complete sibling wrapper and expose it with one atomic rename."""
+    staging = Path(tempfile.mkdtemp(
+        dir=target.parent,
+        prefix=f".{target.name}.",
+        suffix=".tmp",
+    ))
+    removed_link = False
+    try:
+        _write_text_fsync(
+            staging / "SKILL.md",
+            build_codex_skill_text(skill_dir / "SKILL.md"),
+        )
+        _write_text_fsync(
+            staging / ADAPTED_MARKER,
+            "generated by ai-toolkit for Codex\n",
+        )
+        _sync_auxiliaries(skill_dir, staging)
+        _fsync_directory(staging)
+        if replace_managed_link:
+            if not _points_to(target, skill_dir):
+                raise RuntimeError(f"Codex skill target changed during sync: {target}")
+            target.unlink()
+            removed_link = True
+        elif target.exists() or target.is_symlink():
+            raise RuntimeError(f"Codex skill target appeared during sync: {target}")
+        os.replace(staging, target)
+        _fsync_directory(target.parent)
+        return "adapted"
+    except Exception:
+        _remove_staged_wrapper(staging)
+        if removed_link and not target.exists() and not target.is_symlink():
+            target.symlink_to(skill_dir)
+        raise
+def _update_adapted_wrapper(skill_dir: Path, target: Path) -> str:
+    """Atomically refresh SKILL.md while leaving the managed marker stable."""
+    skill_output = target / "SKILL.md"
+    marker = target / ADAPTED_MARKER
+    if skill_output.is_symlink() or marker.is_symlink():
+        return "skipped"
+    temp_path = _stage_text(
+        skill_output,
+        build_codex_skill_text(skill_dir / "SKILL.md"),
+    )
+    try:
+        os.replace(temp_path, skill_output)
+        _fsync_directory(target)
+    finally:
+        temp_path.unlink(missing_ok=True)
+    _sync_auxiliaries(skill_dir, target)
+    return "adapted"
+def _write_text_fsync(destination: Path, content: str) -> None:
+    with destination.open("x", encoding="utf-8") as handle:
+        handle.write(content)
+        handle.flush()
+        os.fsync(handle.fileno())
+def _fsync_directory(path: Path) -> None:
+    if os.name == "nt":
+        return
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        fd = os.open(path, flags)
+    except OSError as error:
+        if error.errno in _UNSUPPORTED_DIRECTORY_FSYNC_ERRNOS:
+            return
+        raise
+    try:
+        try:
+            os.fsync(fd)
+        except OSError as error:
+            if error.errno not in _UNSUPPORTED_DIRECTORY_FSYNC_ERRNOS:
+                raise
+    finally:
+        os.close(fd)
+def _remove_staged_wrapper(staging: Path) -> None:
+    if staging.is_symlink() or not staging.is_dir():
+        return
+    for child in staging.iterdir():
+        if child.is_symlink() or child.is_file():
+            child.unlink()
+    try:
+        staging.rmdir()
+    except OSError:
+        pass
+def _stage_text(destination: Path, content: str) -> Path:
+    fd, temp_name = tempfile.mkstemp(
+        dir=destination.parent,
+        prefix=f".{destination.name}.",
+        suffix=".tmp",
+    )
+    temp_path = Path(temp_name)
+    try:
+        handle = os.fdopen(fd, "w", encoding="utf-8")
+        fd = -1
+        with handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return temp_path
+    except Exception:
+        if fd >= 0:
+            os.close(fd)
+        temp_path.unlink(missing_ok=True)
+        raise
+def _sync_auxiliaries(skill_dir: Path, target: Path) -> None:
+    expected = {child.name for child in skill_dir.iterdir() if child.name != "SKILL.md"}
+    for child in sorted(skill_dir.iterdir()):
+        if child.name == "SKILL.md":
+            continue
+        destination = target / child.name
+        if destination.is_symlink():
+            if _points_to(destination, child):
                 continue
-        if item.is_dir() and (item / ADAPTED_MARKER).is_file() and not src.is_dir():
-            shutil.rmtree(item)
+            continue
+        if destination.exists():
+            continue
+        destination.symlink_to(child)
+    source_root = skill_dir.resolve()
+    for destination in target.iterdir():
+        if destination.name in expected | {"SKILL.md", ADAPTED_MARKER}:
+            continue
+        if destination.is_symlink() and _is_relative_to(
+            _symlink_target(destination), source_root
+        ):
+            destination.unlink()
+def _remove_managed_wrapper(path: Path, skills_src_resolved: Path) -> bool:
+    if not _is_adapted_wrapper(path):
+        return False
+    children = list(path.iterdir())
+    for child in children:
+        if child.name in {"SKILL.md", ADAPTED_MARKER}:
+            if child.is_symlink() or not child.is_file():
+                return False
+            continue
+        if not child.is_symlink():
+            return False
+        if not _is_relative_to(_symlink_target(child), skills_src_resolved):
+            return False
+    for child in children:
+        child.unlink()
+    path.rmdir()
+    return True
 def _is_relative_to(path: Path, parent: Path) -> bool:
@@ -194,113 +499,58 @@ def _render_frontmatter(entries: list[tuple[str, str]]) -> str:
     return "\n".join(f"{key}: {value}" for key, value in entries)
-def _adapt_frontmatter(entries: list[tuple[str, str]]) -> list[tuple[str, str]]:
-    adapted: list[tuple[str, str]] = []
-    for key, value in entries:
-        if key in {"context", "agent", "model"}:
-            continue
-        if key == "description":
-            stripped = _strip_quotes(value)
-            value = f'"{stripped} Codex-adapted: uses native subagents and plan tracking."'
-        elif key == "allowed-tools":
-            value = ", ".join(_adapt_allowed_tools(value))
-        adapted.append((key, value))
-    return adapted
-def _adapt_allowed_tools(value: str) -> list[str]:
-    tools = []
-    for tool in [item.strip() for item in value.split(",") if item.strip()]:
-        if tool in CLAUDE_ONLY_TOOLS:
+def _adapt_body(body: str, platform: str) -> str:
+    label = _PLATFORM_LABELS[platform]
+    body = _replace_agent_calls(body, label)
+    body = body.replace("Agent Teams", f"coordinated {label}-native subagents")
+    body = body.replace("`Agent` tool", f"{label}-native subagents")
+    body = body.replace("the `Agent` tool", f"{label}-native subagents")
+    body = body.replace("Agent tool", f"{label}-native subagents")
+    for token, replacement in _semantic_replacements(platform).items():
+        body = body.replace(token, replacement)
+    if platform == "codex":
+        body = _POSITIONAL_ARGUMENT_RE.sub(
+            lambda match: f"the user-supplied positional task detail {match.group(1)}",
+            body,
+        )
+    return f"{_translation_note(platform).strip()}\n\n{body.strip()}\n"
+def _replace_agent_calls(body: str, label: str) -> str:
+    """Replace balanced Agent calls without consuming surrounding markdown."""
+    rendered: list[str] = []
+    cursor = 0
+    while match := _AGENT_START_RE.search(body, cursor):
+        rendered.append(body[cursor:match.start()])
+        end = _balanced_call_end(body, match.end() - 1)
+        rendered.append(
+            f"Delegate this independent work to a suitable {label}-native subagent."
+        )
+        cursor = end
+    rendered.append(body[cursor:])
+    return "".join(rendered)
+def _balanced_call_end(text: str, opening_parenthesis: int) -> int:
+    depth = 1
+    quote: str | None = None
+    is_escaped = False
+    for index in range(opening_parenthesis + 1, len(text)):
+        character = text[index]
+        if quote is not None:
+            if is_escaped:
+                is_escaped = False
+            elif character == "\\":
+                is_escaped = True
+            elif character == quote:
+                quote = None
             continue
-        if tool not in tools:
-            tools.append(tool)
-    for tool in CODEX_DELEGATION_TOOLS:
-        if tool not in tools:
-            tools.append(tool)
-    return tools
-def _adapt_body(body: str) -> str:
-    body = body.replace(
-        "## MANDATORY: You MUST use the Agent tool",
-        "## MANDATORY: Use Codex subagents for delegation",
-    )
-    body = body.replace("`Agent` tool", "Codex subagent tools")
-    body = body.replace("the `Agent` tool", "Codex subagent tools")
-    body = body.replace("Agent tool", "Codex subagent tools")
-    body = body.replace("Agent Teams", "parallel Codex subagents")
-    body = body.replace(
-        "Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`",
-        "Requires: native Codex subagent support (`spawn_agent`, `send_input`, `wait_agent`, `close_agent`)",
-    )
-    body = body.replace(
-        "Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set; warn if not",
-        "Confirm the user explicitly wants delegated/subagent execution before launching workers",
-    )
-    body = body.replace(
-        "export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
-        "# No extra environment variable is required in Codex",
-    )
-    body = body.replace("TaskCreate", "update_plan")
-    body = body.replace("TaskList", "update_plan")
-    body = body.replace("TaskUpdate", "update_plan")
-    body = body.replace("TaskGet", "wait_agent")
-    body = body.replace("TaskOutput", "wait_agent")
-    body = body.replace("TaskStop", "close_agent")
-    body = body.replace("SendMessage", "send_input")
-    body = body.replace("TeamCreate", "spawn_agent")
-    body = body.replace("TeamDelete", "close_agent")
-    body = _MULTILINE_AGENT_CALL_RE.sub(_replace_multiline_agent_call, body)
-    body = _SINGLE_AGENT_CALL_RE.sub(_replace_single_agent_call, body)
-    if "$ARGUMENTS" in body:
-        body = body.replace("$ARGUMENTS", f"$ARGUMENTS\n{_CODEX_NOTE.rstrip()}", 1)
-    return body
-def _replace_single_agent_call(match: re.Match[str]) -> str:
-    role = match.group(1)
-    prompt = match.group(2)
-    agent_type = _codex_agent_type(role, prompt)
-    escaped_prompt = prompt.replace('"', "'")
-    return (
-        f'spawn_agent(agent_type="{agent_type}", fork_context=True, '
-        f'message="Act as {role}. {escaped_prompt}")'
-    )
-def _replace_multiline_agent_call(match: re.Match[str]) -> str:
-    role = match.group(1)
-    prompt = match.group(3).replace('"', "'")
-    return (
-        "spawn_agent(\n"
-        f'  agent_type="{_codex_agent_type(role, prompt)}",\n'
-        "  fork_context=True,\n"
-        f'  message="Act as {role}. {prompt}"\n'
-        ")"
-    )
-def _codex_agent_type(role: str, prompt: str) -> str:
-    role_l = role.lower()
-    prompt_l = prompt.lower()
-    if role_l == "explorer-agent":
-        return "explorer"
-    if any(token in prompt_l for token in ("read-only", "review", "audit", "trace", "map ", "analyze")):
-        return "default"
-    if any(token in prompt_l for token in (
-        "own files:", "implement", "write ", "apply", "build ", "update ",
-        "create ", "execute ", "fix", "document", "deploy",
-    )):
-        return "worker"
-    return "default"
-def _strip_quotes(value: str) -> str:
-    value = value.strip()
-    if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
-        return value[1:-1]
-    return value
+        if character in {"'", '"'}:
+            quote = character
+        elif character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+            if depth == 0:
+                return index + 1
+    raise ValueError(f"Unbalanced Agent call at character {opening_parenthesis}")