@softspark/ai-toolkit 4.16.0 → 4.17.0

package/scripts/generate_copilot.py

@@ -974,6 +974,23 @@ def _is_managed_skill_dir(path: Path) -> bool:
     return path.is_dir() and not path.is_symlink() and _is_managed(skill_file)
 
 
+def _is_skill_remnant(path: Path) -> bool:
+    """Asset-only leftover of a legacy managed skill.
+
+    Pre-manifest toolkit versions tracked only SKILL.md as managed, so their
+    cleanup removed SKILL.md and left reference/ and scripts/ assets behind.
+    Without SKILL.md the directory is not a functional Copilot skill, so it is
+    safe to rebuild in place; a directory that still has any SKILL.md (managed
+    or not) is never classified as a remnant.
+    """
+    return (
+        path.is_dir()
+        and not path.is_symlink()
+        and not (path / "SKILL.md").exists()
+        and not (path / "SKILL.md").is_symlink()
+    )
+
+
 def _managed_skill_paths(path: Path) -> set[Path]:
     manifest = path / SKILL_MANIFEST
     if not manifest.is_file() or manifest.is_symlink():
@@ -999,7 +1016,8 @@ def _has_user_skill_extras(path: Path) -> bool:
 
 
 def _copy_user_skill_extras(existing: Path, staging: Path,
-                            generated_paths: set[Path]) -> None:
+                            generated_paths: set[Path],
+                            *, skip_stale_assets: bool = False) -> None:
     """Preserve files a user added inside a previously managed skill."""
     old_managed = _managed_skill_paths(existing)
     for source in sorted(existing.rglob("*")):
@@ -1011,6 +1029,8 @@ def _copy_user_skill_extras(existing: Path, staging: Path,
         if not source.is_file():
             continue
         if relative in generated_paths:
+            if skip_stale_assets:
+                continue
             raise RuntimeError(
                 f"Copilot skill update would overwrite a user asset: {source}"
             )
@@ -1046,7 +1066,10 @@ def _stage_skill(skills_root: Path, source_dir: Path,
             encoding="utf-8",
         )
         if existing is not None:
-            _copy_user_skill_extras(existing, staging, generated_paths)
+            _copy_user_skill_extras(
+                existing, staging, generated_paths,
+                skip_stale_assets=_is_skill_remnant(existing),
+            )
         return staging, name
     except Exception:
         shutil.rmtree(staging, ignore_errors=True)
@@ -1058,7 +1081,10 @@ def _replace_skill_dir(staging: Path, destination: Path) -> None:
     backup: Path | None = None
     try:
         if destination.exists():
-            if destination.is_symlink() or not _is_managed_skill_dir(destination):
+            if destination.is_symlink() or not (
+                _is_managed_skill_dir(destination)
+                or _is_skill_remnant(destination)
+            ):
                 raise RuntimeError(
                     f"Refusing user-owned Copilot skill collision: {destination}"
                 )
@@ -1125,7 +1151,12 @@ def _sync_copilot_skills(customization_root: Path, *, label: str) -> None:
         expected_dirs.add(destination_name)
         existing = destination if destination.exists() else None
         if existing is not None and not _is_managed_skill_dir(existing):
-            raise RuntimeError(f"Refusing user-owned Copilot skill collision: {destination}")
+            if not _is_skill_remnant(existing):
+                raise RuntimeError(f"Refusing user-owned Copilot skill collision: {destination}")
+            print(
+                f"Note: rebuilding asset-only Copilot skill remnant '{destination}'",
+                file=sys.stderr,
+            )
         staging, rendered_name = _stage_skill(skill_root, source_dir, existing)
         if rendered_name != logical_name:
             shutil.rmtree(staging, ignore_errors=True)

package/scripts/install.py

@@ -51,7 +51,7 @@ from emission import agent_count as count_agents, skill_count as count_skills
 
 # Step modules
 from install_steps.symlinks import install_agents, install_skills, clean_legacy_commands
-from install_steps.hooks import install_hooks
+from install_steps.hooks import cleanup_retired_output_filter, install_hooks
 from install_steps.markers import install_marker_files, inject_rules, refresh_url_hooks, refresh_url_mcp
 from install_steps.ai_tools import install_ai_tools, install_local_project, run_script
 from install_steps.install_state import (
@@ -435,6 +435,7 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     install_agents(claude_dir, only, skip, dry_run)
     install_skills(claude_dir, only, skip, dry_run)
     clean_legacy_commands(claude_dir, dry_run)
+    cleanup_retired_output_filter(hooks_scripts_dir, dry_run)
     install_hooks(claude_dir, hooks_scripts_dir, only, skip, dry_run)
     install_marker_files(claude_dir, only, skip, dry_run)
 
@@ -841,4 +842,8 @@ def _infer_modules_from_legacy(profile: str, only: str) -> list[str]:
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except RuntimeError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        sys.exit(1)

package/scripts/install_steps/ai_tools.py

@@ -1,7 +1,6 @@
 """Install global and project-local AI tool configs."""
 from __future__ import annotations
 
-import json
 import os
 import shutil
 import subprocess
@@ -15,7 +14,10 @@ from codex_skill_adapter import (
     unmanaged_codex_skill_names,
 )
 from mcp_editors import sync_project_mcp_to_editors
-from secure_fs import SecureDestination, run_secure_transaction
+from output_filter_retirement import (
+    PROJECT_POLICY_NAME,
+    managed_project_policy,
+)
 from injection import (
     collapse_blank_runs as _collapse_blank_runs,
     strip_all_sections as _strip_all_sections,
@@ -23,11 +25,6 @@ from injection import (
 )
 
 
-OUTPUT_FILTER_POLICY_NAME = "ai-toolkit-output-filter.json"
-OUTPUT_FILTER_OWNER_NAME = ".ai-toolkit-output-filter.owner"
-OUTPUT_FILTER_OWNER_MARKER = b"ai-toolkit-output-filter-policy-v1\n"
-
-
 def install_ai_tools(target_dir: Path, rules_dir: Path,
                      dry_run: bool,
                      editors: list[str] | None = None,
@@ -399,6 +396,24 @@ def _cleanup_retired_windsurf_surfaces(cwd: Path) -> None:
         print("  Migrated: removed undocumented .devin/skills toolkit pointer")
 
 
+def _cleanup_retired_output_filter_policy(cwd: Path) -> None:
+    """Remove the per-project policy the v4.16.x tool-output filter wrote.
+
+    Only the owner-marked pair is reclaimed; a policy file the user wrote by
+    hand has no marker and is left untouched.
+    """
+    managed = managed_project_policy(cwd / ".claude")
+    if not managed:
+        return
+    for path in managed:
+        try:
+            path.unlink()
+        except OSError as error:
+            print(f"  Warning: kept .claude/{path.name} ({error})")
+            return
+    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."""
     from generate_cline_rules import generate as gen_cline_rules
@@ -757,10 +772,11 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
             print(f"  Would inject language rules: {', '.join(language_modules)}")
         if merged_config:
             print("  Would apply merged config from extends")
-        if merged_config and merged_config.get("toolOutputFilter") is not None:
-            print("  Would write: .claude/ai-toolkit-output-filter.json")
-        else:
-            print("  Would remove: managed project output-filter policy (if present)")
+        if managed_project_policy(cwd / ".claude"):
+            print(
+                "  Would migrate: remove retired .claude/"
+                f"{PROJECT_POLICY_NAME}"
+            )
         return
 
     (cwd / ".claude").mkdir(parents=True, exist_ok=True)
@@ -770,12 +786,7 @@ def install_local_project(rules_dir: Path, dry_run: bool, reset: bool,
 
     _create_local_claude_md(cwd, reset)
     _create_local_settings(cwd, reset)
-    configured_policy = (
-        merged_config.get("toolOutputFilter")
-        if merged_config is not None
-        else None
-    )
-    _sync_local_output_filter_policy(cwd, configured_policy)
+    _cleanup_retired_output_filter_policy(cwd)
 
     legacy_local_hooks = cwd / ".claude" / "hooks.json"
     if legacy_local_hooks.is_file():
@@ -893,88 +904,6 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
         print("  Saved: .softspark-toolkit-extends.json (resolution metadata)")
 
 
-def _sync_local_output_filter_policy(
-    cwd: Path,
-    configured: dict | None,
-) -> None:
-    """Atomically synchronize the toolkit-owned per-project output policy."""
-    policy_path = cwd / ".claude" / OUTPUT_FILTER_POLICY_NAME
-    owner_path = cwd / ".claude" / OUTPUT_FILTER_OWNER_NAME
-    policy_destination = SecureDestination(
-        policy_path, cwd, "project output-filter policy",
-    )
-    owner_destination = SecureDestination(
-        owner_path, cwd, "project output-filter owner marker",
-    )
-    destinations = [policy_destination, owner_destination]
-
-    try:
-        policy_content = (
-            _materialize_output_filter_policy(configured)
-            if configured is not None
-            else None
-        )
-    except (
-        AttributeError,
-        json.JSONDecodeError,
-        OSError,
-        RuntimeError,
-        TypeError,
-        ValueError,
-    ) as error:
-        print(f"  Warning: project output-filter policy not changed: {error}")
-        return
-
-    def mutate(transaction) -> None:
-        owner = transaction.initial_content(owner_destination)
-        existing_policy = transaction.initial_content(policy_destination)
-        if owner is None and existing_policy is not None:
-            print("  Kept: user-owned .claude/ai-toolkit-output-filter.json")
-            return
-        if owner not in (None, OUTPUT_FILTER_OWNER_MARKER):
-            print("  Kept: untrusted .claude output-filter ownership marker")
-            return
-
-        if policy_content is None:
-            if owner == OUTPUT_FILTER_OWNER_MARKER:
-                transaction.unlink(policy_destination)
-                transaction.unlink(owner_destination)
-                print("  Removed: managed project output-filter policy")
-            return
-
-        transaction.atomic_write(policy_destination, policy_content, 0o600)
-        if owner is None:
-            transaction.atomic_write(
-                owner_destination,
-                OUTPUT_FILTER_OWNER_MARKER,
-                0o600,
-            )
-        print("  Wrote: .claude/ai-toolkit-output-filter.json")
-
-    try:
-        run_secure_transaction(destinations, mutate)
-    except RuntimeError as error:
-        print(f"  Warning: project output-filter policy not changed: {error}")
-
-
-def _materialize_output_filter_policy(configured: dict) -> bytes:
-    """Merge a partial project policy over canonical safe defaults."""
-    default_path = app_dir / "output-filter-policy.json"
-    with open(default_path, encoding="utf-8") as handle:
-        defaults = json.load(handle)
-    policy = dict(defaults)
-    policy.update(configured)
-    recovery = dict(defaults.get("recovery", {}))
-    recovery.update(configured.get("recovery", {}))
-    policy["recovery"] = recovery
-
-    from config_validator import validate_project_config
-    errors = validate_project_config({"toolOutputFilter": policy})
-    if errors:
-        raise RuntimeError("invalid output-filter policy: " + "; ".join(errors))
-    return (json.dumps(policy, indent=2, sort_keys=True) + "\n").encode()
-
-
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
     """Install Claude language-rule entrypoints for a project.
 

package/scripts/install_steps/hooks.py

@@ -7,6 +7,32 @@ import subprocess
 from pathlib import Path
 
 from _common import app_dir, should_install, toolkit_dir
+from output_filter_retirement import (
+    cleanup_global_artifacts,
+    find_global_artifacts,
+)
+
+
+def cleanup_retired_output_filter(hooks_scripts_dir: Path, dry_run: bool) -> None:
+    """Reclaim the v4.16.x tool-output filter files left on disk by an upgrade.
+
+    Runs outside ``should_install`` because the feature is gone: an install
+    that skips the hooks component still must not leave an orphaned hook
+    script, a global policy, or private recovery data behind. Silent when the
+    machine never ran v4.16.x.
+    """
+    toolkit_data_dir = hooks_scripts_dir.parent
+
+    if dry_run:
+        for label in find_global_artifacts(toolkit_data_dir):
+            print(f"  Would migrate: remove retired output-filter {label}")
+        return
+
+    removed, warnings = cleanup_global_artifacts(toolkit_data_dir)
+    for label in removed:
+        print(f"  Migrated: removed retired output-filter {label}")
+    for warning in warnings:
+        print(f"  Warning: output-filter retirement {warning}")
 
 
 def install_hooks(claude_dir: Path, hooks_scripts_dir: Path,
@@ -61,13 +87,6 @@ def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
     for runtime_file in sorted(hooks_src.glob("*.json")):
         shutil.copy2(runtime_file, hooks_scripts_dir / runtime_file.name)
         copied += 1
-    output_filter_policy = app_dir / "output-filter-policy.json"
-    policy_destination = hooks_scripts_dir / output_filter_policy.name
-    # The global policy is user configuration: seed it once, never overwrite,
-    # so `ai-toolkit update` cannot silently reset an enabled mode to off.
-    if output_filter_policy.is_file() and not policy_destination.exists():
-        shutil.copy2(output_filter_policy, policy_destination)
-        copied += 1
     print(f"  Copied: {copied} hook scripts to ~/.softspark/ai-toolkit/hooks/")
     legacy_hooks = claude_dir / "hooks"
     if legacy_hooks.is_symlink():
@@ -78,8 +97,6 @@ def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
 # Python helpers that hooks invoke at runtime. Kept narrow on purpose — only
 # scripts that a deployed hook actually executes belong here.
 HOOK_RUNTIME_SCRIPTS: tuple[str, ...] = (
-    "output_filter_cli.py",
-    "output_filter_hook.py",
     "session_state.py",
     "session_token_stats.py",
     "test_cohesion.py",
@@ -107,21 +124,6 @@ def _copy_hook_runtime_scripts(scripts_dst: Path) -> None:
         shutil.copy2(src, dst)
         dst.chmod(dst.stat().st_mode | 0o111)
         copied += 1
-    output_filter_src = scripts_src / "tool_output_filter"
-    if output_filter_src.is_dir():
-        output_filter_dst = scripts_dst / output_filter_src.name
-        # Prune first: dirs_exist_ok alone never removes modules deleted in a
-        # newer release, and a stale .py at sys.path[0] would shadow the
-        # shipped implementation under `python3 -S`.
-        if output_filter_dst.is_dir() and not output_filter_dst.is_symlink():
-            shutil.rmtree(output_filter_dst)
-        shutil.copytree(
-            output_filter_src,
-            output_filter_dst,
-            dirs_exist_ok=True,
-            ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
-        )
-        copied += 1
     if copied:
         print(f"  Copied: {copied} hook runtime assets to ~/.softspark/ai-toolkit/scripts/")
 

package/scripts/merge-hooks.py

@@ -54,6 +54,15 @@ LEGACY_TOOLKIT_HOOKS = {
     ],
 }
 
+# Hook scripts older releases installed and current releases no longer ship.
+# Claude Code rewrites settings.json without the "_source" tag, so a retired
+# entry cannot be reclaimed by tag, and it cannot be reclaimed by signature
+# either because the matching entry is gone from the toolkit hooks.json. The
+# script path under the toolkit-owned hooks directory is the durable marker.
+RETIRED_HOOK_SCRIPTS = (
+    "ai-toolkit/hooks/filter-tool-output.sh",
+)
+
 
 def load_json(path: str) -> dict:
     """Load and parse a JSON file.
@@ -91,6 +100,25 @@ def _is_toolkit_entry(entry: dict) -> bool:
     return False
 
 
+def _is_retired_toolkit_entry(entry: dict) -> bool:
+    """Check if every handler in an entry runs a retired toolkit hook script.
+
+    Requiring *all* handlers to match keeps a user entry that merely shares an
+    event with a retired hook, and keeps entries that chain their own command
+    after the toolkit one.
+    """
+    handlers = entry.get("hooks", [])
+    if not handlers:
+        return False
+    for hook in handlers:
+        if not isinstance(hook, dict):
+            return False
+        command = hook.get("command", "")
+        if not any(script in command for script in RETIRED_HOOK_SCRIPTS):
+            return False
+    return True
+
+
 def _entry_signature(entry: dict) -> tuple:
     """Return the behavior-defining parts of a hook entry.
 
@@ -112,7 +140,7 @@ def _entry_signature(entry: dict) -> tuple:
 
 
 def strip_toolkit(hooks: dict, toolkit_hooks: dict | None = None) -> dict:
-    """Remove entries tagged with ai-toolkit or matching legacy toolkit hooks."""
+    """Remove ai-toolkit entries: tagged, legacy-signature, or retired script."""
     legacy_signatures: dict[str, set[tuple]] = {}
     if toolkit_hooks:
         for event, entries in toolkit_hooks.items():
@@ -137,7 +165,10 @@ def strip_toolkit(hooks: dict, toolkit_hooks: dict | None = None) -> dict:
             if not _is_toolkit_entry(e)
             and not (
                 isinstance(e, dict)
-                and _entry_signature(e) in signatures
+                and (
+                    _entry_signature(e) in signatures
+                    or _is_retired_toolkit_entry(e)
+                )
             )
         ]
         if filtered: