@softspark/ai-toolkit 4.15.0 → 4.16.0

package/scripts/generate_copilot_hooks.py

@@ -18,6 +18,9 @@ import tempfile
 from pathlib import Path
 from typing import Any
 
+import secure_fs
+from secure_fs import SecureDestination, run_secure_transaction
+
 
 OWNER_KEY = "AI_TOOLKIT_HOOK_OWNER"
 OWNER_VALUE = "ai-toolkit"
@@ -433,13 +436,11 @@ def _validate_entry(event: str, entry: Any) -> None:
             raise ValueError(f"Copilot {event} {key} must be positive")
 
 
-def _is_managed_config(path: Path) -> bool:
-    if path.is_symlink() or not path.is_file():
-        return False
+def _is_managed_config_content(content: bytes) -> bool:
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
+        data = json.loads(content.decode("utf-8"))
         _validate_document(data)
-    except (OSError, json.JSONDecodeError, ValueError):
+    except (UnicodeError, json.JSONDecodeError, ValueError):
         return False
     entries = [entry for values in data["hooks"].values() for entry in values]
     return bool(entries) and all(
@@ -448,12 +449,28 @@ def _is_managed_config(path: Path) -> bool:
     )
 
 
+def _is_managed_config(path: Path) -> bool:
+    if path.is_symlink() or not path.is_file():
+        return False
+    try:
+        return _is_managed_config_content(path.read_bytes())
+    except OSError:
+        return False
+
+
+def _is_managed_script_content(content: bytes) -> bool:
+    try:
+        return SCRIPT_MARKER in content[:256].decode("utf-8")
+    except UnicodeError:
+        return False
+
+
 def _is_managed_script(path: Path) -> bool:
     if path.is_symlink() or not path.is_file():
         return False
     try:
-        return SCRIPT_MARKER in path.read_text(encoding="utf-8")[:256]
-    except (OSError, UnicodeError):
+        return _is_managed_script_content(path.read_bytes())
+    except OSError:
         return False
 
 
@@ -553,6 +570,106 @@ def copilot_home(home: Path | None = None) -> Path:
     return base / ".copilot"
 
 
+def _cleanup_targets(
+    target_dir: Path,
+    config_root: Path | None,
+) -> tuple[Path, Path, Path, list[SecureDestination]]:
+    """Resolve and validate every hook-cleanup destination without mutation."""
+    target_dir = Path(target_dir).expanduser().absolute()
+    project_install = config_root is None
+    customization_root = (
+        target_dir / ".github"
+        if project_install
+        else Path(config_root).expanduser().absolute()
+    )
+    hooks_dir = customization_root / "hooks"
+    assets_dir = hooks_dir / "ai-toolkit"
+    config_path = hooks_dir / CONFIG_NAME
+    script_path = assets_dir / SCRIPT_NAME
+    _assert_safe_paths([
+        (customization_root, "customization root"),
+        (hooks_dir, "hooks directory"),
+        (assets_dir, "hook assets directory"),
+        (config_path, "hook config"),
+        (script_path, "hook runtime"),
+    ])
+    existing_paths: list[tuple[Path, str]] = []
+    if config_path.exists():
+        existing_paths.append((config_path, "hook config"))
+    if script_path.exists():
+        existing_paths.append((script_path, "hook runtime"))
+    trusted_root = target_dir if project_install else customization_root
+    destinations = [
+        SecureDestination(path, trusted_root, f"Copilot {label}")
+        for path, label in existing_paths
+    ]
+    return hooks_dir, config_path, script_path, destinations
+
+
+def _require_secure_cleanup() -> None:
+    if secure_fs.SECURE_DIR_FD:
+        return
+    raise RuntimeError(
+        "Copilot hook cleanup requires POSIX dir_fd and O_NOFOLLOW; "
+        "No files were changed"
+    )
+
+
+def preflight_cleanup(
+    target_dir: Path,
+    *,
+    config_root: Path | None = None,
+) -> None:
+    """Fail before installer mutations when hook cleanup cannot run safely."""
+    _, _, _, destinations = _cleanup_targets(target_dir, config_root)
+    if not destinations:
+        return
+    _require_secure_cleanup()
+    run_secure_transaction(destinations, lambda _transaction: None)
+
+
+def cleanup(target_dir: Path, *, config_root: Path | None = None) -> None:
+    """Remove only the managed Copilot hook bundle for a profile downgrade."""
+    hooks_dir, config_path, script_path, destinations = _cleanup_targets(
+        target_dir,
+        config_root,
+    )
+    if not destinations:
+        return
+    _require_secure_cleanup()
+
+    def remove_managed(transaction) -> bool:
+        contents = {
+            destination.path: transaction.initial_content(destination)
+            for destination in destinations
+        }
+        config_content = contents.get(config_path)
+        script_content = contents.get(script_path)
+        config_owned = (
+            config_content is None or _is_managed_config_content(config_content)
+        )
+        script_owned = (
+            script_content is None or _is_managed_script_content(script_content)
+        )
+        if not config_owned or not script_owned:
+            print(
+                f"Warning: preserving user-owned Copilot hook bundle at '{hooks_dir}'",
+                file=sys.stderr,
+            )
+            return False
+        for destination in destinations:
+            transaction.unlink(destination)
+        return True
+
+    if run_secure_transaction(destinations, remove_managed):
+        label = (
+            ".github/hooks"
+            if config_root is None
+            else str(hooks_dir)
+        )
+        print(f"  Removed managed: {label}/{CONFIG_NAME}")
+
+
 def generate(target_dir: Path, *, config_root: Path | None = None) -> None:
     """Generate repository hooks, or user hooks when ``config_root`` is set."""
     target_dir = Path(target_dir).expanduser().absolute()

package/scripts/generate_gemini_hooks.py

@@ -26,7 +26,9 @@ Writes `<target-dir>/.gemini/settings.json` (merge-safe, idempotent).
 from __future__ import annotations
 
 import json
+import os
 import sys
+import tempfile
 from pathlib import Path
 
 HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
@@ -121,28 +123,49 @@ def merge_hooks(existing_hooks: dict, toolkit_hooks: dict) -> dict:
     return merged
 
 
+def _write_settings_atomic(settings_path: Path, settings: dict) -> None:
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=settings_path.parent,
+            prefix=f".{settings_path.name}.",
+            encoding="utf-8",
+            delete=False,
+        ) as temp_file:
+            json.dump(settings, temp_file, indent=4, ensure_ascii=False, sort_keys=True)
+            temp_file.write("\n")
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+            temp_path = Path(temp_file.name)
+        os.replace(temp_path, settings_path)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+
+
 def generate(target_dir: Path) -> Path:
     """Write `<target_dir>/.gemini/settings.json` and return its path."""
     gemini_dir = target_dir / ".gemini"
+    if gemini_dir.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Gemini directory: {gemini_dir}")
     gemini_dir.mkdir(parents=True, exist_ok=True)
     settings_path = gemini_dir / "settings.json"
+    if settings_path.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Gemini settings: {settings_path}")
 
     settings: dict = {}
     if settings_path.is_file():
-        try:
-            with open(settings_path, encoding="utf-8") as f:
-                settings = json.load(f)
-            if not isinstance(settings, dict):
-                settings = {}
-        except (json.JSONDecodeError, OSError):
-            settings = {}
+        with open(settings_path, encoding="utf-8") as f:
+            settings = json.load(f)
+        if not isinstance(settings, dict):
+            raise ValueError(f"{settings_path} must contain a JSON object")
 
     existing_hooks = settings.get("hooks") if isinstance(settings.get("hooks"), dict) else {}
     settings["hooks"] = merge_hooks(existing_hooks or {}, build_toolkit_hooks())
 
-    with open(settings_path, "w", encoding="utf-8") as f:
-        json.dump(settings, f, indent=4, ensure_ascii=False, sort_keys=True)
-        f.write("\n")
+    _write_settings_atomic(settings_path, settings)
     return settings_path
 
 

package/scripts/generate_opencode_plugin.py

@@ -32,7 +32,6 @@ Usage:
 from __future__ import annotations
 
 import argparse
-import sys
 from pathlib import Path
 
 PLUGIN_BODY = r"""// ai-toolkit opencode plugin — bridges shared Bash hooks to opencode events.
@@ -49,8 +48,9 @@ PLUGIN_BODY = r"""// ai-toolkit opencode plugin — bridges shared Bash hooks to
 const HOOKS_DIR = `${process.env.HOME}/.softspark/ai-toolkit/hooks`;
 
 /** Invoke a Bash hook with a JSON payload on stdin. */
-async function runHook($, script, payload) {
+async function runHook($, script, payload, blockOnExit2 = false) {
   const scriptPath = `${HOOKS_DIR}/${script}`;
+  let result;
   try {
     const input = JSON.stringify(payload ?? {});
     const proc = $`bash ${scriptPath}`.env({
@@ -59,23 +59,34 @@ async function runHook($, script, payload) {
     });
     proc.stdin.write(input);
     proc.stdin.end();
-    const result = await proc.quiet().nothrow();
-    if (result.exitCode !== 0 && result.exitCode !== 2) {
-      // Exit 2 is the toolkit's "block" signal — pass through to opencode as a guard.
-      process.stderr.write(
-        `[ai-toolkit] ${script} exited ${result.exitCode}\n${result.stderr.toString()}`
-      );
-    }
-    return result.exitCode;
+    result = await proc.quiet().nothrow();
   } catch (err) {
     process.stderr.write(`[ai-toolkit] failed to run ${script}: ${err.message}\n`);
     return 0;
   }
+  if (result.exitCode === 2 && blockOnExit2) {
+    const detail = result.stderr.toString().trim();
+    throw new Error(
+      `[ai-toolkit] ${script} blocked tool execution${detail ? `: ${detail}` : ""}`
+    );
+  }
+  if (result.exitCode !== 0 && result.exitCode !== 2) {
+    process.stderr.write(
+      `[ai-toolkit] ${script} exited ${result.exitCode}\n${result.stderr.toString()}`
+    );
+  }
+  return result.exitCode;
 }
 
 export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
   event: async ({ event }) => {
-    const payload = { event: event.type, project, directory, worktree };
+    const payload = {
+      event: event.type,
+      session_id: event?.properties?.sessionID,
+      project,
+      directory,
+      worktree,
+    };
     switch (event.type) {
       case "session.created":
         await runHook($, "session-start.sh", payload);
@@ -106,12 +117,15 @@ export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
   "tool.execute.before": async (input, output) => {
     const payload = {
       event: "tool.execute.before",
+      session_id: input?.sessionID,
+      tool_name: input?.tool,
+      tool_input: output?.args,
       tool: input?.tool,
       args: output?.args,
       project,
     };
     if (input?.tool === "bash") {
-      await runHook($, "guard-destructive.sh", payload);
+      await runHook($, "guard-destructive.sh", payload, true);
       await runHook($, "commit-quality.sh", payload);
     }
   },
@@ -119,6 +133,8 @@ export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
   "tool.execute.after": async (input, output) => {
     const payload = {
       event: "tool.execute.after",
+      session_id: input?.sessionID,
+      tool_name: input?.tool,
       tool: input?.tool,
       result: output,
       project,

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.
 
@@ -1267,6 +1366,16 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
     emit_pointer = not _claude_skills_discoverable(cwd)
 
     if "copilot" in eds:
+        from generate_copilot import (
+            generate as gen_copilot_dir,
+            preflight_cleanup as preflight_copilot_cleanup,
+        )
+        if not add_copilot_dir:
+            from generate_copilot_hooks import (
+                preflight_cleanup as preflight_copilot_hook_cleanup,
+            )
+            preflight_copilot_cleanup(cwd)
+            preflight_copilot_hook_cleanup(cwd)
         inject_with_rules(
             "generate-copilot.sh",
             cwd / ".github" / "copilot-instructions.md",
@@ -1275,16 +1384,19 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         _install_copilot_agents_md(cwd, rules_dir)
         # Agents and skills are the minimal Copilot surface. Standard and above
         # add path instructions, prompts, and native lifecycle hooks.
-        from generate_copilot import generate as gen_copilot_dir
         gen_copilot_dir(
             cwd,
             language_modules=language_modules,
             rules_dir=rules_dir,
             emit_prompts=add_copilot_dir,
             emit_instructions=add_copilot_dir,
+            cleanup_disabled=not add_copilot_dir,
         )
         if add_copilot_dir:
             _try_generator("generate_copilot_hooks", cwd)
+        else:
+            from generate_copilot_hooks import cleanup as cleanup_copilot_hooks
+            cleanup_copilot_hooks(cwd)
 
     if "cursor" in eds:
         inject_with_rules(

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: