@softspark/ai-toolkit 4.15.1 → 4.16.1

package/scripts/install_steps/ai_tools.py

@@ -1,6 +1,7 @@
 """Install global and project-local AI tool configs."""
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import subprocess
@@ -14,6 +15,7 @@ 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 injection import (
     collapse_blank_runs as _collapse_blank_runs,
     strip_all_sections as _strip_all_sections,
@@ -21,6 +23,11 @@ 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,
@@ -750,6 +757,10 @@ 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)")
         return
 
     (cwd / ".claude").mkdir(parents=True, exist_ok=True)
@@ -759,6 +770,12 @@ 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)
 
     legacy_local_hooks = cwd / ".claude" / "hooks.json"
     if legacy_local_hooks.is_file():
@@ -832,8 +849,8 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
 
     # Inject constitution amendments
     amendments = merged.get("constitution", {}).get("amendments", [])
-    # Filter to non-toolkit articles (6+)
-    custom_amendments = [a for a in amendments if a.get("article", 0) >= 6]
+    # Articles I-VII are toolkit-owned; inherited custom amendments start at VIII.
+    custom_amendments = [a for a in amendments if a.get("article", 0) >= 8]
     if custom_amendments:
         constitution_file = cwd / ".claude" / "constitution.md"
         if constitution_file.is_file():
@@ -876,6 +893,88 @@ 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

@@ -61,6 +61,13 @@ 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():
@@ -71,6 +78,8 @@ 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",
@@ -98,8 +107,23 @@ 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 scripts to ~/.softspark/ai-toolkit/scripts/")
+        print(f"  Copied: {copied} hook runtime assets to ~/.softspark/ai-toolkit/scripts/")
 
 
 def _run_merge_hooks(action: str, *args: str) -> None:

package/scripts/output_filter_cli.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""Manual and hook entry points for native tool-output filtering."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from tool_output_filter.contracts import FilterMode, FilterRequest
+from tool_output_filter.contracts import (
+    DEFAULT_MAX_INPUT_BYTES,
+    DEFAULT_MIN_SAVINGS_BYTES,
+    DEFAULT_MIN_SAVINGS_RATIO,
+)
+from tool_output_filter.engine import filter_output
+from tool_output_filter.hook_runtime import run_hook
+from tool_output_filter.input import read_bounded_text
+from tool_output_filter.policy import OutputFilterPolicy, load_policy
+from tool_output_filter.recovery import (
+    EphemeralRecoveryStore,
+    clean_owned_repo_recovery,
+    clean_session,
+    recover_by_handle,
+)
+
+if TYPE_CHECKING:
+    import argparse
+
+_OWNER_MARKER = "ai-toolkit-output-filter-policy-v1"
+_INSPECT_PROFILES = frozenset({"repeat-lines", "tap-success"})
+
+
+def _infer_repo_root(start: Path) -> Path | None:
+    # realpath keeps the repo key aligned with the bash hooks, which resolve
+    # symlinks via `git rev-parse --show-toplevel`.
+    candidate_path = Path(
+        os.path.realpath(os.path.expanduser(str(start)))
+    )
+    if not candidate_path.is_dir():
+        return None
+    for candidate in (candidate_path, *candidate_path.parents):
+        git_marker = candidate / ".git"
+        if git_marker.is_dir() or git_marker.is_file():
+            return candidate
+    return candidate_path
+
+
+def _session_base_for_repo(repo_root: Path) -> Path:
+    repo_key = "-" + str(repo_root).replace("/", "-").lstrip("-")
+    return (
+        Path.home()
+        / ".softspark"
+        / "ai-toolkit"
+        / "sessions"
+        / repo_key
+    )
+
+
+def _manual_session_base() -> Path | None:
+    project_directory = os.environ.get("CLAUDE_PROJECT_DIR")
+    repo_root = _infer_repo_root(
+        Path(project_directory) if project_directory else Path.cwd()
+    )
+    return _session_base_for_repo(repo_root) if repo_root is not None else None
+
+
+def _is_regular_file(path: Path) -> bool:
+    return path.is_file() and not path.is_symlink()
+
+
+def _is_registered_project(project_root: Path) -> bool:
+    """Trust only projects registered via `ai-toolkit install --local`.
+
+    The owner marker is a public constant, so a cloned repo must never be
+    able to self-enable filtering with it. Mirrors filter-tool-output.sh.
+    """
+    registry = (
+        Path.home() / ".softspark" / "ai-toolkit" / "projects.json"
+    )
+    if not _is_regular_file(registry):
+        return False
+    try:
+        data = json.loads(registry.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return False
+    projects = data.get("projects") if isinstance(data, dict) else None
+    if not isinstance(projects, list):
+        return False
+    root_text = str(project_root)
+    return any(
+        isinstance(entry, dict) and entry.get("path") == root_text
+        for entry in projects
+    )
+
+
+def _trusted_project_policy(project_root: Path) -> Path | None:
+    managed_directory = project_root / ".claude"
+    if project_root.is_symlink() or managed_directory.is_symlink():
+        return None
+    if not _is_registered_project(project_root):
+        return None
+    policy_path = managed_directory / "ai-toolkit-output-filter.json"
+    owner_path = managed_directory / ".ai-toolkit-output-filter.owner"
+    if not _is_regular_file(policy_path) or not _is_regular_file(owner_path):
+        return None
+    try:
+        owner_text = owner_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    # The bash hook's $(<file) strips trailing newlines; accept the same.
+    if owner_text.rstrip("\n") != _OWNER_MARKER:
+        return None
+    return policy_path
+
+
+def _resolve_policy_path(explicit_path: Path | None) -> Path | None:
+    if explicit_path is not None:
+        return explicit_path
+    # Same resolution as filter-tool-output.sh: the project directory only,
+    # never its parents, so `status` reports what the hook will actually do.
+    project_directory = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    project_policy = _trusted_project_policy(Path(project_directory))
+    if project_policy is not None:
+        return project_policy
+    global_policy = (
+        Path.home()
+        / ".softspark"
+        / "ai-toolkit"
+        / "hooks"
+        / "output-filter-policy.json"
+    )
+    return global_policy if _is_regular_file(global_policy) else None
+
+
+def _default_policy() -> OutputFilterPolicy:
+    return OutputFilterPolicy(
+        mode=FilterMode.OFF,
+        profiles=("repeat-lines", "tap-success"),
+    )
+
+
+def _run_status(policy_path: Path | None) -> int:
+    resolved_path = _resolve_policy_path(policy_path)
+    if resolved_path is None:
+        policy = _default_policy()
+    else:
+        try:
+            policy = load_policy(resolved_path)
+        except (OSError, TypeError, ValueError, KeyError):
+            return 2
+    output = {
+        "mode": policy.mode.value,
+        "profiles": list(policy.profiles),
+        "maxInputBytes": policy.max_input_bytes,
+        "minSavingsBytes": policy.min_savings_bytes,
+        "minSavingsRatio": policy.min_savings_ratio,
+        "recovery": {
+            "mode": "ephemeral",
+            "ttlMinutes": policy.ttl_minutes,
+            "maxSessionBytes": policy.max_session_bytes,
+        },
+    }
+    print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
+def _run_inspect(args: argparse.Namespace) -> int:
+    if not _valid_inspect_arguments(args):
+        return 2
+    try:
+        raw_output = read_bounded_text(
+            sys.stdin.buffer,
+            max_bytes=args.max_input_bytes,
+        )
+    except (TypeError, UnicodeDecodeError, ValueError):
+        return 2
+    if raw_output is None:
+        report = {
+            "profile": args.profile,
+            "eligible": False,
+            "outcome": "passthrough",
+            "fallbackReason": "input-too-large",
+            "inputBytesAtLeast": args.max_input_bytes + 1,
+            "maxInputBytes": args.max_input_bytes,
+        }
+        print(json.dumps(report, separators=(",", ":")))
+        return 0
+    request = FilterRequest(
+        output=raw_output,
+        mode=FilterMode.OBSERVE,
+        profile_id=args.profile,
+        max_input_bytes=args.max_input_bytes,
+        min_savings_bytes=args.min_savings_bytes,
+        min_savings_ratio=args.min_savings_ratio,
+    )
+    result = filter_output(request)
+    telemetry = result.telemetry
+    input_bytes = len(raw_output.encode("utf-8"))
+    report = {
+        "profile": args.profile,
+        "eligible": result.outcome == "observed",
+        "outcome": result.outcome,
+        "fallbackReason": result.fallback_reason,
+        "inputBytes": input_bytes,
+        "candidateBytes": (
+            telemetry.output_bytes if telemetry is not None else input_bytes
+        ),
+        "inputLines": len(raw_output.splitlines()),
+        "candidateLines": (
+            telemetry.output_lines
+            if telemetry is not None
+            else len(raw_output.splitlines())
+        ),
+    }
+    print(json.dumps(report, ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
+def _valid_inspect_arguments(args: argparse.Namespace) -> bool:
+    """Reject unsafe manual limits before consuming stdin."""
+    return (
+        args.profile in _INSPECT_PROFILES
+        and 1 <= args.max_input_bytes <= DEFAULT_MAX_INPUT_BYTES
+        and 0 <= args.min_savings_bytes <= DEFAULT_MAX_INPUT_BYTES
+        and math.isfinite(args.min_savings_ratio)
+        and 0.0 <= args.min_savings_ratio <= 1.0
+    )
+
+
+def _run_recover(args: argparse.Namespace) -> int:
+    base_directory = args.base_directory or _manual_session_base()
+    if base_directory is None:
+        return 2
+    try:
+        if args.session_id:
+            with EphemeralRecoveryStore(
+                base_directory,
+                session_identifier=args.session_id,
+            ) as recovery:
+                response = recovery.load(args.handle)
+        else:
+            response = recover_by_handle(base_directory, args.handle)
+    except (OSError, RuntimeError, TypeError, ValueError):
+        return 2
+    if response is None:
+        return 1
+    print(json.dumps(response, ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
+def _run_clean(args: argparse.Namespace) -> int:
+    base_directory = args.base_directory or _manual_session_base()
+    if base_directory is None:
+        return 2
+    try:
+        if args.session_id:
+            if args.expired:
+                with EphemeralRecoveryStore(
+                    base_directory,
+                    session_identifier=args.session_id,
+                ) as recovery:
+                    removed = recovery.clean_expired()
+                scope = "expired"
+            else:
+                removed = clean_session(
+                    base_directory,
+                    args.session_id,
+                )
+                scope = "all"
+        elif args.expired:
+            return 2
+        else:
+            removed = clean_owned_repo_recovery(base_directory)
+            scope = "all"
+    except (OSError, RuntimeError, TypeError, ValueError):
+        return 2
+    print(json.dumps({"removed": removed, "scope": scope}, separators=(",", ":")))
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Inspect and safely filter supported tool output"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    hook = subparsers.add_parser("hook")
+    hook.add_argument("--policy", type=Path, required=True)
+    status = subparsers.add_parser("status")
+    status.add_argument("--policy", type=Path)
+    inspect = subparsers.add_parser("inspect")
+    inspect.add_argument("--profile", required=True)
+    inspect.add_argument(
+        "--max-input-bytes",
+        type=int,
+        default=DEFAULT_MAX_INPUT_BYTES,
+    )
+    inspect.add_argument(
+        "--min-savings-bytes",
+        type=int,
+        default=DEFAULT_MIN_SAVINGS_BYTES,
+    )
+    inspect.add_argument(
+        "--min-savings-ratio",
+        type=float,
+        default=DEFAULT_MIN_SAVINGS_RATIO,
+    )
+    recover = subparsers.add_parser("recover")
+    recover.add_argument("handle")
+    recover.add_argument("--base-directory", type=Path)
+    recover.add_argument("--session-id")
+    clean = subparsers.add_parser("clean")
+    clean.add_argument("--base-directory", type=Path)
+    clean.add_argument("--session-id")
+    clean.add_argument("--expired", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    if (
+        len(arguments) == 3
+        and arguments[0] == "hook"
+        and arguments[1] == "--policy"
+    ):
+        return run_hook(Path(arguments[2]))
+    args = _build_parser().parse_args(arguments)
+    if args.command == "hook":
+        return run_hook(args.policy)
+    if args.command == "status":
+        return _run_status(args.policy)
+    if args.command == "inspect":
+        return _run_inspect(args)
+    if args.command == "recover":
+        return _run_recover(args)
+    if args.command == "clean":
+        return _run_clean(args)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/output_filter_hook.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Lean process entry point for the Claude output-filter hook."""
+
+from __future__ import annotations
+
+import sys
+
+from tool_output_filter.hook_runtime import run_hook
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    if (
+        len(arguments) != 3
+        or arguments[0] != "hook"
+        or arguments[1] != "--policy"
+    ):
+        return 2
+    return run_hook(arguments[2])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/plugin_schema.py

@@ -11,7 +11,14 @@ from pathlib import Path
 
 
 # Required top-level fields
-REQUIRED_FIELDS = ("name", "description", "version", "domain", "type", "status")
+REQUIRED_FIELDS = (
+    "name",
+    "description",
+    "version",
+    "domain",
+    "type",
+    "status",
+)
 
 # Valid status values
 VALID_STATUSES = frozenset({"stable", "experimental", "deprecated"})
@@ -39,6 +46,24 @@ VALID_HOOK_EVENTS = frozenset({
 })
 
 
+def _validate_requires(data: dict) -> list[str]:
+    if "requires" not in data:
+        return ["Missing required field: requires"]
+
+    requires = data["requires"]
+    if not isinstance(requires, dict) or not requires:
+        return ["'requires' must be a non-empty dictionary"]
+
+    errors: list[str] = []
+    for dependency, constraint in requires.items():
+        if not isinstance(dependency, str) or not dependency.strip():
+            errors.append("requires keys must be non-empty strings")
+            continue
+        if not isinstance(constraint, str) or not constraint.strip():
+            errors.append(f"requires.{dependency} must be a non-empty string")
+    return errors
+
+
 def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
     """Validate a plugin manifest dict.
 
@@ -50,6 +75,7 @@ def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
     for field in REQUIRED_FIELDS:
         if field not in data or not data[field]:
             errors.append(f"Missing required field: {field}")
+    errors.extend(_validate_requires(data))
 
     # Validate status
     status = data.get("status", "")