@softspark/ai-toolkit 4.24.0 → 4.25.0

package/scripts/install_steps/ai_tools.py

@@ -88,17 +88,29 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
             if add_hooks:
                 print("  Would generate: ~/.gemini/settings.json (hooks)")
             if add_native_surfaces:
-                print("  Would generate: ~/.gemini/commands/, ~/.gemini/skills/")
+                print(
+                    "  Would generate: ~/.gemini/commands/, ~/.gemini/skills/, "
+                    "~/.gemini/agents/"
+                )
         else:
             inject_with_rules("generate-gemini.sh", gemini_file, rules_dir)
-            # Hooks (~/.gemini/settings.json), commands (~/.gemini/commands/),
-            # and the skills pointer (~/.gemini/skills/) are documented user-tier
-            # surfaces — install them globally, gated like the local install.
+            # Hooks (~/.gemini/settings.json), commands, the skills pointer,
+            # and native agents are documented user-tier surfaces. Install
+            # them globally with the same profile gates as the local install.
             if add_hooks:
                 _try_generator("generate_gemini_hooks", target_dir)
+            else:
+                from generate_gemini_hooks import cleanup as cleanup_gemini_hooks
+
+                cleanup_gemini_hooks(target_dir)
             if add_native_surfaces:
                 _try_generator("generate_gemini_commands", target_dir)
                 _try_generator("generate_gemini_skills", target_dir)
+                _try_generator("generate_gemini_agents", target_dir)
+            else:
+                from generate_gemini_agents import cleanup as cleanup_gemini_agents
+
+                cleanup_gemini_agents(target_dir)
         installed.append("gemini")
 
     if "augment" in eds:
@@ -120,13 +132,21 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
 
     if "cline" in eds:
         if dry_run:
-            print("  Would generate: ~/Documents/Cline/Rules/ai-toolkit-*.md")
+            print(
+                "  Would generate: ~/.cline/rules/ai-toolkit-*.md + "
+                "~/Documents/Cline/Rules/ai-toolkit-*.md"
+            )
+            if add_hooks:
+                print(
+                    "  Would generate: ~/.cline/hooks/<Event> + "
+                    "~/Documents/Cline/Hooks/<Event>"
+                )
             if _claude_skills_discoverable(target_dir):
                 print("  Would reuse: ~/.claude/skills/ (Cline-compatible discovery)")
             else:
                 print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
         else:
-            _install_cline_global(target_dir, rules_dir)
+            _install_cline_global(target_dir, rules_dir, add_hooks=add_hooks)
         installed.append("cline")
 
     if "roo" in eds:
@@ -163,8 +183,14 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
         if dry_run:
             print("  Would inject: ~/.config/opencode/{AGENTS.md, agents/, "
                   "commands/, plugins/ai-toolkit-hooks.js, opencode.json}")
+            if add_native_surfaces:
+                print("  Would generate: ~/.config/opencode/skills/ (profile=full)")
         else:
-            _install_opencode_global(target_dir, rules_dir)
+            _install_opencode_global(
+                target_dir,
+                rules_dir,
+                add_native_surfaces=add_native_surfaces,
+            )
         installed.append("opencode")
 
     if "cursor" in eds:
@@ -211,20 +237,51 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
         installed.append("copilot")
 
     if "antigravity" in eds:
-        # Antigravity RULES stay project-local, but the skill pointer has a
-        # documented global surface: ~/.gemini/config/skills (all Antigravity
-        # products) and ~/.gemini/antigravity-cli/skills (CLI-private).
+        # Antigravity rules stay project-local. CLI and IDE/shared product each
+        # own a canonical skill root; full additionally installs subagents.
         if dry_run:
-            print("  Would generate: ~/.gemini/config/skills/, ~/.gemini/antigravity-cli/skills/ (skill pointer)")
+            print(
+                "  Would generate: ~/.gemini/antigravity-cli/skills/ "
+                "(current CLI skills)"
+            )
+            print(
+                "  Would generate: ~/.gemini/config/skills/ "
+                "(current IDE/shared skills)"
+            )
+            if add_hooks:
+                print("  Would generate: ~/.gemini/config/hooks.json + hooks runtime")
+            if add_native_surfaces:
+                print("  Would generate: ~/.gemini/config/agents/ (profile=full)")
         else:
             from generate_antigravity import generate_global as gen_antigravity_global
             gen_antigravity_global(target_dir)
+            if add_hooks:
+                _try_generator(
+                    "generate_antigravity_hooks",
+                    target_dir,
+                    global_install=True,
+                )
+            else:
+                from generate_antigravity_hooks import cleanup as cleanup_hooks
+
+                cleanup_hooks(target_dir, global_install=True)
+            antigravity_config = target_dir / ".gemini" / "config"
+            if add_native_surfaces:
+                _try_generator(
+                    "generate_antigravity_agents",
+                    target_dir,
+                    config_root=antigravity_config,
+                )
+            else:
+                from generate_antigravity_agents import cleanup as cleanup_agents
+
+                cleanup_agents(target_dir, config_root=antigravity_config)
         installed.append("antigravity")
 
     print()
     print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
     print("  Note: Cursor and Antigravity RULES stay project-local (no mergeable "
-          "global file surface); their global installs cover hooks/skills only. "
+          "global file surface); Antigravity full also installs native agents. "
           "Use 'ai-toolkit install --local' for full per-project setup.")
 
     return installed
@@ -418,21 +475,46 @@ def _cleanup_retired_output_filter_policy(cwd: Path) -> None:
     print(f"  Migrated: removed retired .claude/{PROJECT_POLICY_NAME}")
 
 
-def _install_cline_global(target_dir: Path, rules_dir: Path) -> None:
-    """Install Cline global rules in the documented ~/.cline directory."""
+def _install_cline_global(
+    target_dir: Path,
+    rules_dir: Path,
+    *,
+    add_hooks: bool,
+) -> None:
+    """Install native Cline CLI surfaces plus extension compatibility."""
     from generate_cline_rules import generate as gen_cline_rules
 
-    # Cline reads GLOBAL rules from ~/Documents/Cline/Rules/ (docs.cline.bot);
-    # ~/.cline/rules/ is not a Cline-read path.
-    rules_root = target_dir / "Documents" / "Cline" / "Rules"
-    gen_cline_rules(
-        target_dir,
-        rules_dir=rules_dir,
-        output_root=rules_root,
-        emit_workflows=False,
-        managed_scopes=("standard", "custom"),
+    for rules_root, label in (
+        (target_dir / ".cline" / "rules", "~/.cline/rules"),
+        (
+            target_dir / "Documents" / "Cline" / "Rules",
+            "~/Documents/Cline/Rules",
+        ),
+    ):
+        gen_cline_rules(
+            target_dir,
+            rules_dir=rules_dir,
+            output_root=rules_root,
+            emit_workflows=False,
+            managed_scopes=("standard", "custom"),
+        )
+        print(f"  Created: {label}/ai-toolkit-*.md")
+
+    from generate_cline_hooks import (
+        cleanup as cleanup_cline_hooks,
+        generate_extension_global,
+        generate_global,
     )
-    print("  Created: ~/Documents/Cline/Rules/ai-toolkit-*.md")
+
+    extension_hooks = target_dir / "Documents" / "Cline" / "Hooks"
+    if add_hooks:
+        generate_global(target_dir)
+        generate_extension_global(target_dir)
+        print("  Created: ~/.cline/hooks/<Event>")
+        print("  Created: ~/Documents/Cline/Hooks/<Event>")
+    else:
+        cleanup_cline_hooks(target_dir)
+        cleanup_cline_hooks(target_dir, hooks_root=extension_hooks)
 
     from generate_cline_skills import generate as gen_cline_skills
     gen_cline_skills(target_dir, emit_skill_pointer=not _claude_skills_discoverable(target_dir))
@@ -494,13 +576,19 @@ def _aider_default_model() -> str:
     return DEFAULT_CLAUDE_MODELS["sonnet"]
 
 
-def _install_opencode_global(target_dir: Path, rules_dir: Path) -> None:
+def _install_opencode_global(
+    target_dir: Path,
+    rules_dir: Path,
+    *,
+    add_native_surfaces: bool,
+) -> None:
     """Install opencode at the global level (~/.config/opencode/).
 
     Creates:
       - ~/.config/opencode/AGENTS.md (marker injection with rules)
       - ~/.config/opencode/agents/ai-toolkit-*.md (subagents)
       - ~/.config/opencode/commands/ai-toolkit-*.md (slash commands)
+      - ~/.config/opencode/skills/*/SKILL.md (native skills, profile=full)
       - ~/.config/opencode/plugins/ai-toolkit-hooks.js (hook bridge)
       - ~/.config/opencode/opencode.json (MCP merge, preserves user keys)
     """
@@ -527,6 +615,32 @@ def _install_opencode_global(target_dir: Path, rules_dir: Path) -> None:
     msg += ")"
     print(msg)
 
+    if add_native_surfaces:
+        from generate_opencode_skills import generate as gen_opencode_skills
+
+        written, removed, preserved = gen_opencode_skills(
+            target_dir,
+            config_root=opencode_home,
+        )
+        msg = f"  Created: ~/.config/opencode/skills/ ({written} skills"
+        if removed:
+            msg += f", {removed} stale removed"
+        if preserved:
+            msg += f", {preserved} user-owned preserved"
+        print(msg + ")")
+    else:
+        from generate_opencode_skills import cleanup as cleanup_opencode_skills
+
+        removed, _ = cleanup_opencode_skills(
+            target_dir,
+            config_root=opencode_home,
+        )
+        if removed:
+            print(
+                "  Removed: ~/.config/opencode/skills/ "
+                f"({removed} managed skills)"
+            )
+
     from generate_opencode_plugin import generate as gen_opencode_plugin
     gen_opencode_plugin(target_dir, config_root=opencode_home)
     print("  Created: ~/.config/opencode/plugins/ai-toolkit-hooks.js")
@@ -660,6 +774,9 @@ _EDITOR_MARKERS: dict[str, str] = {
     # .windsurf/ markers stay to detect legacy installs.
     ".devin/rules": "windsurf",
     ".clinerules": "cline",
+    ".cline/rules": "cline",
+    ".cline/hooks": "cline",
+    ".cline/agents": "cline",
     ".roomodes": "roo",
     ".roo/rules": "roo",
     ".aider.conf.yml": "aider",
@@ -692,8 +809,8 @@ def _detect_editors(cwd: Path) -> list[str]:
         if not p.exists():
             continue
         if marker == ".agents/skills" and _is_pointer_only_skills_dir(p):
-            # The Antigravity CLI pointer skill also lives in .agents/skills/;
-            # only real (materialized) skills indicate a Codex install.
+            # The canonical workspace Antigravity pointer also lives in
+            # .agents/skills/; only materialized skills indicate Codex.
             continue
         found.add(editor)
     return sorted(found)
@@ -1040,6 +1157,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
 
     add_copilot_dir = profile in {"standard", "strict", "full"}
     add_gemini_hooks = profile in {"standard", "strict", "full"}
+    add_cline_hooks = profile in {"standard", "strict", "full"}
     add_native_surfaces = profile == "full"
 
     # Editor-specific dry-run messages
@@ -1047,7 +1165,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         "copilot":      "  Would inject: .github/copilot-instructions.md + AGENTS.md",
         "cursor":       "  Would generate: .cursorrules + .cursor/rules/*.mdc",
         "windsurf":     "  Would generate: .windsurfrules + .devin/rules/*.md + .windsurf/rules/*.md",
-        "cline":        "  Would generate: .clinerules/*.md",
+        "cline":        "  Would generate: .cline/rules/*.md + .clinerules/*.md",
         "roo":          "  Would generate: .roomodes + .roo/rules/*.md",
         "aider":        "  Would generate: .aider.conf.yml + CONVENTIONS.md",
         "augment":      "  Would generate: .augment/rules/ai-toolkit-*.md",
@@ -1079,6 +1197,13 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
                   ".github/hooks/ (profile >= standard)")
     if "gemini" in eds and add_gemini_hooks:
         print("  Would generate: .gemini/settings.json hooks (profile >= standard)")
+    if "antigravity" in eds and add_gemini_hooks:
+        print("  Would generate: .agents/hooks.json + hooks runtime (profile >= standard)")
+    if "cline" in eds and add_cline_hooks:
+        print(
+            "  Would generate: .cline/hooks/<Event> + "
+            ".clinerules/hooks/<Event> (profile >= standard)"
+        )
     if add_native_surfaces:
         if "cursor" in eds:
             print("  Would generate: .cursor/hooks.json + .cursor/agents/ + .cursor/skills/ (profile=full)")
@@ -1090,7 +1215,14 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
             print("  Would generate: .augment/agents/ + .augment/commands/ + "
                   "$HOME/.augment/settings.json + .augment/skills/ (profile=full)")
         if "gemini" in eds:
-            print("  Would generate: .gemini/commands/ + .gemini/skills/ (profile=full)")
+            print(
+                "  Would generate: .gemini/commands/ + .gemini/skills/ + "
+                ".gemini/agents/ (profile=full)"
+            )
+        if "antigravity" in eds:
+            print("  Would generate: .agents/agents/ (profile=full)")
+        if "opencode" in eds:
+            print("  Would generate: .opencode/skills/ (profile=full)")
     if "codex" in eds:
         print("  Would generate: .codex/agents/ native agents")
         print("  Would generate: .agents/skills/ Codex skills")
@@ -1290,6 +1422,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
     _profile = profile if profile in {"minimal", "standard", "strict", "full"} else "standard"
     add_copilot_dir = _profile in {"standard", "strict", "full"}
     add_gemini_hooks = _profile in {"standard", "strict", "full"}
+    add_cline_hooks = _profile in {"standard", "strict", "full"}
     add_native_surfaces = _profile == "full"
     # Skip the editor skill-catalogue pointer when real skills are already
     # discoverable at .claude/skills (project or ~/.claude/skills global):
@@ -1364,11 +1497,6 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             _try_generator("generate_windsurf_skills", cwd)
 
     if "cline" in eds:
-        # Migrate: remove legacy .clinerules single file (replaced by directory)
-        legacy_clinerules = cwd / ".clinerules"
-        if legacy_clinerules.is_file():
-            legacy_clinerules.unlink()
-            print("  Migrated: .clinerules file → .clinerules/ directory")
         from generate_cline_rules import generate as gen_cline_rules
         gen_cline_rules(
             cwd,
@@ -1376,8 +1504,18 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             rules_dir=rules_dir,
             managed_scopes=("standard", "lang", "custom"),
         )
+        if add_cline_hooks:
+            _try_generator("generate_cline_hooks", cwd)
+        else:
+            from generate_cline_hooks import cleanup as cleanup_cline_hooks
+
+            cleanup_cline_hooks(cwd)
         if add_native_surfaces:
             _try_generator("generate_cline_skills", cwd, emit_skill_pointer=emit_pointer)
+        else:
+            from generate_cline_skills import cleanup as cleanup_cline_skills
+
+            cleanup_cline_skills(cwd)
 
     if "roo" in eds:
         roo_output = run_script("generate-roo-modes.sh", capture=True)
@@ -1409,6 +1547,18 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         from generate_antigravity import generate as gen_antigravity
         gen_antigravity(cwd, language_modules=language_modules,
                         rules_dir=rules_dir)
+        if add_gemini_hooks:
+            _try_generator("generate_antigravity_hooks", cwd)
+        else:
+            from generate_antigravity_hooks import cleanup as cleanup_hooks
+
+            cleanup_hooks(cwd)
+        if add_native_surfaces:
+            _try_generator("generate_antigravity_agents", cwd)
+        else:
+            from generate_antigravity_agents import cleanup as cleanup_agents
+
+            cleanup_agents(cwd)
 
     if "codex" in eds:
         # AGENTS.md — marker injection; universal coding rules are inlined into
@@ -1442,9 +1592,18 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         )
         if add_gemini_hooks:
             _try_generator("generate_gemini_hooks", cwd)
+        else:
+            from generate_gemini_hooks import cleanup as cleanup_gemini_hooks
+
+            cleanup_gemini_hooks(cwd)
         if add_native_surfaces:
             _try_generator("generate_gemini_commands", cwd)
             _try_generator("generate_gemini_skills", cwd)
+            _try_generator("generate_gemini_agents", cwd)
+        else:
+            from generate_gemini_agents import cleanup as cleanup_gemini_agents
+
+            cleanup_gemini_agents(cwd)
 
     if "opencode" in eds:
         # AGENTS.md — shared with Codex via marker injection (opencode reads same file)
@@ -1470,6 +1629,22 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             msg += f", {removed} stale removed"
         msg += ")"
         print(msg)
+        if add_native_surfaces:
+            from generate_opencode_skills import generate as gen_opencode_skills
+
+            written, removed, preserved = gen_opencode_skills(cwd)
+            msg = f"  Created: .opencode/skills/ ({written} skills"
+            if removed:
+                msg += f", {removed} stale removed"
+            if preserved:
+                msg += f", {preserved} user-owned preserved"
+            print(msg + ")")
+        else:
+            from generate_opencode_skills import cleanup as cleanup_opencode_skills
+
+            removed, _ = cleanup_opencode_skills(cwd)
+            if removed:
+                print(f"  Removed: .opencode/skills/ ({removed} managed skills)")
         # .opencode/plugins/ai-toolkit-hooks.js — lifecycle hook bridge
         from generate_opencode_plugin import generate as gen_opencode_plugin
         gen_opencode_plugin(cwd)

package/scripts/mcp_editors.py

@@ -520,12 +520,13 @@ def _normalize_server(editor: str, server: dict) -> dict:
 
 
 def _normalize_antigravity_server(server: dict) -> dict:
-    """Validate Antigravity's native MCP schema without rewriting transports."""
+    """Validate and emit Antigravity's current ``serverUrl`` MCP schema."""
     if not isinstance(server, dict):
         raise ValueError("Antigravity MCP server configuration must be an object")
 
     data = copy.deepcopy(server)
     data.pop("_source", None)
+    data.pop("transport", None)
     if "httpUrl" in data:
         raise ValueError("Antigravity MCP does not support the legacy 'httpUrl' field")
 
@@ -538,6 +539,13 @@ def _normalize_antigravity_server(server: dict) -> dict:
     transport_key = transport_keys[0]
     _require_antigravity_string(data, transport_key)
 
+    # Current Antigravity documentation emits only serverUrl. Accept the old
+    # portable `url` input so existing .mcp.json templates keep working, but
+    # never persist that legacy spelling in native Antigravity configuration.
+    if transport_key == "url":
+        data["serverUrl"] = data.pop("url")
+        transport_key = "serverUrl"
+
     if transport_key == "command":
         _validate_antigravity_stdio(data)
     else:

package/scripts/plugin.py

@@ -603,10 +603,30 @@ def _ensure_claude_settings() -> Path:
     return settings_path
 
 
+def _clear_dangling_link(path: Path, label: str) -> bool:
+    """Drop a symlink whose target no longer exists, so install can relink it.
+
+    A toolkit upgrade replaces app/ wholesale, which leaves every ~/.claude link
+    into the old package pointing at nothing. The install guard treated such a
+    link as installed (`exists() or is_symlink()`), reported OK and repaired
+    nothing — the user was left with a dead link and a green log. Only dangling
+    links are removed: a live link or a real file is user content and stays.
+    """
+    if path.is_symlink() and not path.exists():
+        try:
+            path.unlink()
+        except OSError:
+            return False
+        print(f"    Dangling {label} link removed: {path.name}")
+        return True
+    return False
+
+
 def _install_claude_skills(pack: dict, pack_dir: Path, installed_items: list[str]) -> None:
     for skill in pack.get("includes", {}).get("skills", []):
         skill_dir = CLAUDE_DIR / "skills" / skill
         source_dir = _resolve_skill_source(pack_dir, skill)
+        _clear_dangling_link(skill_dir, "skill")
         if skill_dir.exists() or skill_dir.is_symlink():
             print(f"    OK skill: {skill}")
         elif source_dir:
@@ -622,6 +642,7 @@ def _install_claude_agents(pack: dict, pack_dir: Path, installed_items: list[str
     for agent in pack.get("includes", {}).get("agents", []):
         agent_file = CLAUDE_DIR / "agents" / f"{agent}.md"
         source_file = _resolve_agent_source(pack_dir, agent)
+        _clear_dangling_link(agent_file, "agent")
         if agent_file.exists() or agent_file.is_symlink():
             print(f"    OK agent: {agent}")
         elif source_file is not None:

package/scripts/plugin_schema.py

@@ -40,13 +40,14 @@ VALID_TYPES = frozenset({
 
 # Valid hook event names (must match validate.py VALID_HOOK_EVENTS)
 VALID_HOOK_EVENTS = frozenset({
-    "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
-    "PreCompact", "SubagentStop", "UserPromptSubmit", "TaskCompleted",
-    "TeammateIdle", "SubagentStart", "SessionEnd", "PermissionRequest", "Setup",
-    "InstructionsLoaded", "ConfigChange", "PostToolUseFailure", "PostToolBatch",
-    "UserPromptExpansion", "PostCompact", "StopFailure", "CwdChanged",
-    "FileChanged", "PermissionDenied", "Elicitation", "ElicitationResult",
-    "WorktreeCreate", "WorktreeRemove", "TaskCreated",
+    "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
+    "MessageDisplay", "PreToolUse", "PostToolUse", "PostToolUseFailure",
+    "PostToolBatch", "Stop", "StopFailure", "UserPromptExpansion",
+    "SubagentStart", "SubagentStop", "PreCompact", "PostCompact",
+    "PermissionRequest", "PermissionDenied", "Elicitation", "ElicitationResult",
+    "TaskCreated", "TaskCompleted", "TeammateIdle", "WorktreeCreate",
+    "WorktreeRemove", "CwdChanged", "FileChanged", "ConfigChange",
+    "DirectoryAdded", "Setup", "InstructionsLoaded",
 })
 
 

package/scripts/secure_fs.py

@@ -438,6 +438,41 @@ class SecureTransaction:
     def unlink(self, destination: SecureDestination) -> None:
         self._unlink(destination, enforce_snapshot=True)
 
+    def rmdir_empty(
+        self,
+        anchor: SecureDestination,
+        relative: Path,
+    ) -> bool:
+        """Remove an empty directory below a pinned parent without following links.
+
+        This is a post-commit pruning helper. It deliberately returns ``False``
+        for missing, non-empty, or unsafe paths instead of widening a completed
+        file transaction's rollback surface.
+        """
+        if relative.is_absolute() or not relative.parts or ".." in relative.parts:
+            raise RuntimeError(f"Invalid relative directory path: {relative}")
+        pinned = self._get(anchor)
+        if not pinned.materialized:
+            raise RuntimeError(
+                f"Anchor parent was not materialized: {pinned.destination.path}"
+            )
+        directory_fd = os.dup(pinned.parent_fd)
+        try:
+            for part in relative.parts[:-1]:
+                next_fd = os.open(part, _DIRECTORY_FLAGS, dir_fd=directory_fd)
+                os.close(directory_fd)
+                directory_fd = next_fd
+            os.rmdir(relative.parts[-1], dir_fd=directory_fd)
+            os.fsync(directory_fd)
+            return True
+        except OSError:
+            return False
+        finally:
+            try:
+                os.close(directory_fd)
+            except OSError:
+                pass
+
     def _unlink(
         self,
         destination: SecureDestination,