Support controlled multi-install for safe AI agent integrations (#2389)

* support controlled multi-install integrations

* fix: harden multi-install integration state

* refactor: isolate integration runtime helpers

* fix: address copilot review feedback

* fix: address follow-up copilot feedback

* fix: tighten integration switch semantics

* fix: address final copilot review feedback

* fix: harden integration manifest read errors

* fix: refuse symlinked shared infra paths

* test: filter expected self-test preset warning

* test: address copilot review nits

* refactor: centralize safe shared infra writes

* fix: use no-follow writes for shared infra

* fix: keep default integration atomic on template refresh

* fix: harden shared infra error paths

* fix: preflight shared infra and future state schemas

* fix: support nested shared scripts during preflight

* test: tolerate wrapped schema error output

* fix: use safe default mode for shared text writes

* fix: use posix paths in shared skip output

* fix: share project guard for integration use

* fix: centralize spec-kit project guards

* fix: use posix project paths in cli output

* fix: harden shared manifest and upgrade refresh

src/specify_cli/integrations/auggie/__init__.py

@@ -19,3 +19,4 @@ class AuggieIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".augment/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/base.py

@@ -87,6 +87,14 @@ class IntegrationBase(ABC):
     invoke_separator: str = "."
     """Separator used in slash-command invocations (``"."`` → ``/speckit.plan``)."""
 
+    multi_install_safe: bool = False
+    """Whether this integration is declared safe to install alongside others.
+
+    Safe integrations must use a static, unique agent root, command directory,
+    and context file. Registry tests enforce those invariants for every
+    integration that sets this flag.
+    """
+
     # -- Markers for managed context section ------------------------------
 
     CONTEXT_MARKER_START = "<!-- SPECKIT START -->"

src/specify_cli/integrations/claude/__init__.py

@@ -53,6 +53,7 @@ class ClaudeIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "CLAUDE.md"
+    multi_install_safe = True
 
     @staticmethod
     def inject_argument_hint(content: str, hint: str) -> str:

src/specify_cli/integrations/codebuddy/__init__.py

@@ -19,3 +19,4 @@ class CodebuddyIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "CODEBUDDY.md"
+    multi_install_safe = True

src/specify_cli/integrations/codex/__init__.py

@@ -27,6 +27,7 @@ class CodexIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "AGENTS.md"
+    multi_install_safe = True
 
     def build_exec_args(
         self,

src/specify_cli/integrations/cursor_agent/__init__.py

@@ -26,6 +26,7 @@ class CursorAgentIntegration(SkillsIntegration):
     }
 
     context_file = ".cursor/rules/specify-rules.mdc"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/gemini/__init__.py

@@ -19,3 +19,4 @@ class GeminiIntegration(TomlIntegration):
         "extension": ".toml",
     }
     context_file = "GEMINI.md"
+    multi_install_safe = True

src/specify_cli/integrations/iflow/__init__.py

@@ -19,3 +19,4 @@ class IflowIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "IFLOW.md"
+    multi_install_safe = True

src/specify_cli/integrations/junie/__init__.py

@@ -19,3 +19,4 @@ class JunieIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".junie/AGENTS.md"
+    multi_install_safe = True

src/specify_cli/integrations/kilocode/__init__.py

@@ -19,3 +19,4 @@ class KilocodeIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".kilocode/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/kimi/__init__.py

@@ -36,6 +36,7 @@ class KimiIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = "KIMI.md"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/manifest.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -47,6 +48,59 @@ def _validate_rel_path(rel: Path, root: Path) -> Path:
     return resolved
 
 
+def _manifest_path_label(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _ensure_safe_manifest_directory(root: Path, directory: Path) -> None:
+    """Create a manifest directory without following symlinked parents."""
+    root_resolved = root.resolve()
+    try:
+        rel = directory.relative_to(root)
+    except ValueError:
+        label = _manifest_path_label(root, directory)
+        raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+
+    current = root
+    for part in rel.parts:
+        current = current / part
+        label = _manifest_path_label(root, current)
+        if current.is_symlink():
+            raise ValueError(f"Refusing to use symlinked integration manifest directory: {label}")
+        if current.exists():
+            if not current.is_dir():
+                raise ValueError(f"Integration manifest directory path is not a directory: {label}")
+            try:
+                current.resolve().relative_to(root_resolved)
+            except (OSError, ValueError):
+                raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+            continue
+        current.mkdir()
+        try:
+            current.resolve().relative_to(root_resolved)
+        except (OSError, ValueError):
+            raise ValueError(f"Integration manifest directory escapes project root: {label}") from None
+
+
+def _ensure_safe_manifest_destination(root: Path, path: Path) -> None:
+    """Refuse manifest writes that would escape the project or follow symlinks."""
+    root_resolved = root.resolve()
+    _ensure_safe_manifest_directory(root, path.parent)
+    label = _manifest_path_label(root, path)
+    if path.is_symlink():
+        raise ValueError(f"Refusing to overwrite symlinked integration manifest path: {label}")
+    if path.exists():
+        if not path.is_file():
+            raise ValueError(f"Integration manifest path is not a file: {label}")
+        try:
+            path.resolve().relative_to(root_resolved)
+        except (OSError, ValueError):
+            raise ValueError(f"Integration manifest path escapes project root: {label}") from None
+
+
 class IntegrationManifest:
     """Tracks files installed by a single integration.
 
@@ -217,8 +271,19 @@ class IntegrationManifest:
             "files": self._files,
         }
         path = self.manifest_path
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        content = json.dumps(data, indent=2) + "\n"
+        _ensure_safe_manifest_destination(self.project_root, path)
+        fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        temp_path = Path(temp_name)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(content)
+            temp_path.chmod(0o644)
+            _ensure_safe_manifest_destination(self.project_root, path)
+            os.replace(temp_path, path)
+        finally:
+            if temp_path.exists():
+                temp_path.unlink()
         return path
 
     @classmethod

src/specify_cli/integrations/qodercli/__init__.py

@@ -19,3 +19,4 @@ class QodercliIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "QODER.md"
+    multi_install_safe = True

src/specify_cli/integrations/qwen/__init__.py

@@ -19,3 +19,4 @@ class QwenIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "QWEN.md"
+    multi_install_safe = True

src/specify_cli/integrations/roo/__init__.py

@@ -19,3 +19,4 @@ class RooIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".roo/rules/specify-rules.md"
+    multi_install_safe = True

src/specify_cli/integrations/shai/__init__.py

@@ -19,3 +19,4 @@ class ShaiIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "SHAI.md"
+    multi_install_safe = True

src/specify_cli/integrations/tabnine/__init__.py

@@ -19,3 +19,4 @@ class TabnineIntegration(TomlIntegration):
         "extension": ".toml",
     }
     context_file = "TABNINE.md"
+    multi_install_safe = True

src/specify_cli/integrations/trae/__init__.py

@@ -27,6 +27,7 @@ class TraeIntegration(SkillsIntegration):
         "extension": "/SKILL.md",
     }
     context_file = ".trae/rules/project_rules.md"
+    multi_install_safe = True
 
     @classmethod
     def options(cls) -> list[IntegrationOption]:

src/specify_cli/integrations/windsurf/__init__.py

@@ -19,3 +19,4 @@ class WindsurfIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = ".windsurf/rules/specify-rules.md"
+    multi_install_safe = True