@softspark/ai-toolkit 4.16.1 → 4.18.0

package/scripts/doctor.py

@@ -75,7 +75,6 @@ EXPECTED_HOOKS = [
     "subagent-start.sh",
     "subagent-stop.sh",
     "session-end.sh",
-    "filter-tool-output.sh",
 ]
 
 PLANNED_ASSETS = [
@@ -442,25 +441,9 @@ def check_generated_artifacts(dr: DiagResult, fix_mode: bool) -> None:
             else:
                 dr.warn(f"{artifact} missing (run: ai-toolkit generate-all)")
 
-    # Check if AGENTS.md is stale (agents added/removed since generation)
-    agents_md = toolkit_dir / "AGENTS.md"
-    if agents_md.is_file():
-        agents_dir = toolkit_dir / "app" / "agents"
-        actual_agents = sum(1 for f in agents_dir.glob("*.md") if f.is_file()) if agents_dir.is_dir() else 0
-        content = agents_md.read_text(encoding="utf-8")
-        mentioned_agents = len(re.findall(r"^### `", content, re.MULTILINE))
-        if actual_agents != mentioned_agents:
-            if fix_mode:
-                result = subprocess.run(
-                    ["python3", str(toolkit_dir / "scripts" / "generate_agents_md.py")],
-                    capture_output=True,
-                    text=True,
-                )
-                if result.returncode == 0:
-                    agents_md.write_text(result.stdout, encoding="utf-8")
-                    dr.fixed(f"regenerated stale AGENTS.md ({mentioned_agents} -> {actual_agents} entries)")
-            else:
-                dr.warn(f"AGENTS.md may be stale: {mentioned_agents} entries vs {actual_agents} agent files")
+    # AGENTS.md no longer embeds the agent catalog (agents are discovered from
+    # their native directories), so there is no per-entry staleness to check —
+    # presence is covered by the generated-artifacts loop above.
 
     print()
 

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)
 

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: