@softspark/ai-toolkit 2.7.3 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.8.0 — Security Hardening & GHAS Integration (2026-04-18)
+
+### Added
+- **`scripts/audit_skills.py --sarif`** — emits SARIF 2.1.0 JSON compatible with GitHub Advanced Security Code Scanning. Severity maps HIGH→error / WARN→warning / INFO→note. Enables the GitHub Security tab to ingest audit findings directly.
+- **`scripts/audit_skills.py --permissions`** — per-skill tool-permission report (human + `--json` forms). Aggregates skills by tool usage (e.g. "50 skills use Bash"), flags broad Bash+Write+Edit access, prints full skill/invocable/tools table. Security review can now answer "show me every skill that can Bash" in one command.
+- **Checksum pinning for URL-sourced rules and hooks** — `rule_sources.py` and `hook_sources.py` now persist `sha256` of the fetched payload in `sources.json`. Subsequent refreshes log `CHECKSUM CHANGED` when the upstream payload changes. Setting `AI_TOOLKIT_STRICT_PIN=1` turns the mismatch into a hard failure (exit 2) so CI can reject silent upstream tampering.
+- **`SECRET_PLACEHOLDER_PREFIXES`** allowlist in `audit_skills.py` — WARN-level hardcoded-secret patterns now skip values starting with `REPLACE_`, `CHANGEME_`, `CHANGE_ME`, `YOUR_`, `EXAMPLE_`, `PLACEHOLDER_`, `${`, `{{`, `$ENV_`, `$(`, `<`, `xxx`, `XXX`. Fewer false positives on docs and `.env.example` fixtures.
+
+### Changed
+- **npm publish workflow (`.github/workflows/publish.yml`)** now runs with `--provenance` and `id-token: write`. Published tarballs carry a cryptographic provenance attestation visible on npmjs.com and verifiable via `npm audit signatures`.
+- **`scripts/config_resolver.py:_extract_tarball`** passes `filter="data"` to `tarfile.extract` on Python 3.12+. Defense in depth on top of existing path-traversal, symlink, and absolute-path rejection. Future-proofs against the 3.14 default-filter change.
+- **`app/hooks/session-start.sh`** sanitises `VERSION_MSG` with `LC_ALL=C tr -d '"'"'"'\\`$'` before interpolating into `osascript` / `powershell.exe` notification commands. Closes a latent command-injection footgun.
+- **`scripts/install_steps/ai_tools.py`** and **`hooks.py`** — generator and merge-hooks `subprocess.run` calls now have `timeout=120`. A stuck generator produces a clear error instead of hanging `ai-toolkit install` indefinitely.
+- **`app/hooks/commit-quality.sh`** — extracted commit message via a small Python regex instead of fragile shell `grep -oE` chain. Handles commit messages containing mixed `"` and `'` correctly.
+- **`app/hooks/quality-check.sh`** — normalised `|| true` handling across all languages (Python ruff was previously the only one propagating exit status). All language checks are now consistently advisory on the Stop hook.
+- **`bin/ai-toolkit.js:handleAddRule`** — simplified HTTPS/HTTP detection (single `startsWith('https://')` after the `http://` reject).
+- **`package.json` description** shortened from 400+ to 241 characters — stops mid-sentence truncation in npm search. Surfaces the new SARIF + provenance differentiators.
+- **`package.json` `engines`** — removed non-standard `bats` entry (npm ignores unknown engines and warned on install). Bats requirement is documented in `CLAUDE.md` Commands section.
+
+---
+
 ## v2.7.3 — Regenerate llms after Medplum Merge (2026-04-17)
 
 ### Fixed

package/README.md

@@ -10,9 +10,12 @@
 
 ---
 
-## What's New in v2.7.3
+## What's New in v2.8.0
 
-- **`llms.txt` + `llms-full.txt` regenerated** after PR #7 (Medplum/FHIR rules) — catalogs now list `medplum-docs-map.md` and the language-rules reference advertises the correct counts: `14 languages / 73 rule files` (was `13 / 68`).
+- **SARIF + permissions audit** — `audit_skills.py --sarif` emits SARIF 2.1.0 for GitHub Advanced Security Code Scanning; `--permissions` prints per-skill tool usage (e.g. "50 skills use Bash") and flags broad Bash+Write+Edit access.
+- **Signed npm provenance** — the publish workflow now runs with `--provenance`; published tarballs carry a cryptographic build-origin attestation verifiable via `npm audit signatures`.
+- **Checksum-pinned URL sources** — `sources.json` now persists `sha256` of every URL-sourced rule/hook and warns on upstream content change. `AI_TOOLKIT_STRICT_PIN=1` turns mismatches into a hard CI failure.
+- **Security hardening** — `tarfile.extract` uses `filter="data"` on Python 3.12+; `session-start.sh` sanitises `VERSION_MSG` before `osascript`/`powershell.exe`; install-time `subprocess.run` calls now time out at 120 s.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.7.3",
+  "version": "2.8.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/commit-quality.sh

@@ -14,14 +14,17 @@ fi
 # Only check commands that contain "git commit"
 printf '%s' "$COMMAND" | grep -q 'git commit' || exit 0
 
-# Extract commit message from -m flag
-# Handles: git commit -m "msg", git commit -m 'msg', git commit -am "msg"
-MSG=$(printf '%s' "$COMMAND" | grep -oE '\-m\s+["'"'"']([^"'"'"']*)["'"'"']' | head -1 | sed "s/^-m[[:space:]]*[\"']//" | sed "s/[\"']$//")
-
-# Also handle heredoc-style: -m "$(cat <<'EOF' ... EOF )"
-if [ -z "$MSG" ]; then
-    MSG=$(printf '%s' "$COMMAND" | grep -oE '\-m\s+"[^"]*"' | head -1 | sed 's/^-m[[:space:]]*//' | tr -d '"')
-fi
+# Extract commit message from -m flag. Delegated to Python for correct
+# quote handling — the previous shell-regex approach broke on commit messages
+# containing both " and '.
+MSG=$(printf '%s' "$COMMAND" | python3 -c '
+import re, sys
+cmd = sys.stdin.read()
+# Match -m followed by a quoted string (either " or ").
+m = re.search(r"""-m\s+("((?:[^"\\]|\\.)*)"|'"'"'((?:[^'"'"'\\]|\\.)*)'"'"')""", cmd)
+if m:
+    print(m.group(2) if m.group(2) is not None else m.group(3))
+' 2>/dev/null)
 
 # No message found (might be --amend or interactive) — skip
 if [ -z "$MSG" ]; then

package/app/hooks/quality-check.sh

@@ -7,8 +7,12 @@
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
 
+# All lint/typecheck invocations are advisory. They run on the Stop hook and
+# must not block Claude from returning a response, hence the trailing `|| true`.
+# The first 15 lines of output are surfaced to the user; further lines are
+# truncated to keep the context lean.
 if [ -f pyproject.toml ] || [ -f setup.py ]; then
-    ruff check . 2>&1 | head -15
+    ruff check . 2>&1 | head -15 || true
 elif [ -f package.json ] && [ -f tsconfig.json ]; then
     npx tsc --noEmit 2>&1 | head -15 || true
 elif [ -f composer.json ] && [ -f vendor/bin/phpstan ]; then

package/app/hooks/session-start.sh

@@ -14,13 +14,17 @@ TOOLKIT_DIR="$(npm root -g 2>/dev/null)/@softspark/ai-toolkit"
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then
     echo "$VERSION_MSG"
+    # Strip shell/AppleScript/PowerShell metacharacters before interpolating into
+    # notification commands. VERSION_MSG is version_check.py output which should
+    # be plain ASCII, but sanitize anyway as defense in depth.
+    VERSION_MSG_SAFE=$(printf '%s' "$VERSION_MSG" | LC_ALL=C tr -d '"'"'"'\\`$')
     # Desktop notification so user sees update before typing
     if command -v osascript >/dev/null 2>&1; then
-        osascript -e "display notification \"$VERSION_MSG\" with title \"ai-toolkit\"" 2>/dev/null &
+        osascript -e "display notification \"$VERSION_MSG_SAFE\" with title \"ai-toolkit\"" 2>/dev/null &
     elif command -v notify-send >/dev/null 2>&1; then
-        notify-send "ai-toolkit" "$VERSION_MSG" 2>/dev/null &
+        notify-send "ai-toolkit" "$VERSION_MSG_SAFE" 2>/dev/null &
     elif command -v powershell.exe >/dev/null 2>&1; then
-        powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$VERSION_MSG',5,'ai-toolkit',64)" 2>/dev/null &
+        powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$VERSION_MSG_SAFE',5,'ai-toolkit',64)" 2>/dev/null &
     fi
 fi
 

package/bin/ai-toolkit.js

@@ -368,11 +368,11 @@ function handleAddRule(args) {
     process.exit(1);
   }
   // Pass URLs through directly (don't resolve as filesystem path)
-  const isUrl = ruleFile.startsWith('https://') || ruleFile.startsWith('http://');
   if (ruleFile.startsWith('http://')) {
     console.error('Error: only HTTPS URLs are supported. Use https:// for security.');
     process.exit(1);
   }
+  const isUrl = ruleFile.startsWith('https://');
   const absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.7.3",
+  "version": "2.8.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.7.3",
-  "description": "Professional-grade AI coding toolkit: 99 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, opencode), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "2.8.0",
+  "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
     "claude-code",
@@ -77,7 +77,6 @@
     "llms-full.txt"
   ],
   "engines": {
-    "node": ">=18.0.0",
-    "bats": ">=1.8.0 — install via: brew install bats-core (macOS) or apt install bats (Ubuntu)"
+    "node": ">=18.0.0"
   }
 }

package/scripts/add_rule.py

@@ -68,7 +68,7 @@ def main() -> None:
 
         dest = rules_dir / f"{rule_name}.md"
         dest.write_bytes(data)
-        register_url_source(rules_dir, rule_name, source)
+        register_url_source(rules_dir, rule_name, source, content=data)
 
         print(f"Registered: '{rule_name}' -> {dest}")
         print(f"Source URL: {source} (auto-refreshed on update)")

package/scripts/audit_skills.py

@@ -7,9 +7,11 @@ Detects dangerous code patterns, hardcoded secrets, and permission issues.
 Stdlib-only. JSON output to stdout. Non-zero exit on HIGH findings.
 
 Usage:
-    python3 scripts/audit_skills.py [toolkit-dir]          # scan all
-    python3 scripts/audit_skills.py [toolkit-dir] --json   # JSON output
-    python3 scripts/audit_skills.py [toolkit-dir] --ci     # exit 1 on HIGH
+    python3 scripts/audit_skills.py [toolkit-dir]               # scan all
+    python3 scripts/audit_skills.py [toolkit-dir] --json        # JSON output
+    python3 scripts/audit_skills.py [toolkit-dir] --sarif       # SARIF 2.1.0 output
+    python3 scripts/audit_skills.py [toolkit-dir] --permissions # per-skill tool permission report
+    python3 scripts/audit_skills.py [toolkit-dir] --ci          # exit 1 on HIGH
 
 Exit codes:
     0  no HIGH findings
@@ -71,6 +73,13 @@ SECRET_PATTERNS = [
     (r'api_key\s*=\s*["\'][^"\']{8,}["\']', "WARN", "Hardcoded API key"),
 ]
 
+# Placeholder values that the WARN-severity secret patterns must ignore to cut
+# false positives on docs, fixtures, and .env.example-style files.
+SECRET_PLACEHOLDER_PREFIXES = (
+    "REPLACE_", "CHANGEME_", "CHANGE_ME", "YOUR_", "EXAMPLE_", "PLACEHOLDER_",
+    "${", "{{", "$ENV_", "$(", "<", "xxx", "XXX",
+)
+
 # ---------------------------------------------------------------------------
 # Scanner
 # ---------------------------------------------------------------------------
@@ -110,6 +119,16 @@ def scan_file_patterns(filepath: Path, patterns: list[tuple],
                 findings.append(Finding(severity, rel, lineno, regex, desc))
 
 
+def _is_placeholder_value(match: re.Match) -> bool:
+    """Return True if the matched value looks like a docs placeholder."""
+    # Extract content between quotes (group 0 is the full match)
+    inner = re.search(r'["\']([^"\']+)["\']', match.group(0))
+    if not inner:
+        return False
+    value = inner.group(1)
+    return value.startswith(SECRET_PLACEHOLDER_PREFIXES)
+
+
 def scan_secrets(filepath: Path, findings: list[Finding]) -> None:
     """Scan a file for hardcoded secrets."""
     try:
@@ -119,8 +138,15 @@ def scan_secrets(filepath: Path, findings: list[Finding]) -> None:
     rel = str(filepath)
     for lineno, line in enumerate(text.splitlines(), 1):
         for regex, severity, desc in SECRET_PATTERNS:
-            if re.search(regex, line):
-                findings.append(Finding(severity, rel, lineno, regex, desc))
+            m = re.search(regex, line)
+            if not m:
+                continue
+            # Skip placeholder values for WARN-level hardcoded-* patterns.
+            # HIGH-level patterns (real AWS/GitHub/etc. keys) are structural —
+            # no need to allowlist.
+            if severity == "WARN" and _is_placeholder_value(m):
+                continue
+            findings.append(Finding(severity, rel, lineno, regex, desc))
 
 
 def check_frontmatter(skill_dir: Path, findings: list[Finding]) -> None:
@@ -176,6 +202,78 @@ def check_agent(agent_md: Path, findings: list[Finding]) -> None:
         ))
 
 
+# ---------------------------------------------------------------------------
+# Per-skill permission report
+# ---------------------------------------------------------------------------
+
+def collect_permissions(toolkit_root: Path) -> list[dict]:
+    """Read each SKILL.md frontmatter and return permission metadata per skill."""
+    skills = toolkit_root / "app" / "skills"
+    rows: list[dict] = []
+    if not skills.is_dir():
+        return rows
+    for skill_dir in sorted(skills.iterdir()):
+        if not skill_dir.is_dir() or skill_dir.name.startswith("_"):
+            continue
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+        allowed_raw = frontmatter_field(skill_md, "allowed-tools") or ""
+        tools = [t.strip() for t in allowed_raw.split(",") if t.strip()]
+        rows.append({
+            "name": skill_dir.name,
+            "tools": tools,
+            "user_invocable": frontmatter_field(skill_md, "user-invocable") or "",
+            "disable_model_invocation": frontmatter_field(
+                skill_md, "disable-model-invocation"
+            ) or "",
+        })
+    return rows
+
+
+def print_permissions(rows: list[dict], json_mode: bool = False) -> None:
+    """Emit the per-skill permission report."""
+    # Aggregate tool usage counts
+    by_tool: dict[str, list[str]] = {}
+    for row in rows:
+        for tool in row["tools"]:
+            by_tool.setdefault(tool, []).append(row["name"])
+    broad = [
+        row["name"] for row in rows
+        if {"Bash", "Write", "Edit"}.issubset(set(row["tools"]))
+    ]
+
+    if json_mode:
+        report = {
+            "total": len(rows),
+            "by_tool": {k: sorted(v) for k, v in by_tool.items()},
+            "broad_access": sorted(broad),
+            "skills": rows,
+        }
+        print(json.dumps(report, indent=2))
+        return
+
+    print("Skill Permissions Report")
+    print("=" * 40)
+    print(f"Total skills: {len(rows)}")
+    print()
+    print("By tool (skill count):")
+    for tool in sorted(by_tool, key=lambda t: (-len(by_tool[t]), t)):
+        print(f"  {tool:<12} {len(by_tool[tool])}")
+    print()
+    if broad:
+        print(f"Skills with Bash + Write + Edit ({len(broad)}):")
+        for name in sorted(broad):
+            print(f"  - {name}")
+        print()
+    print("Full table:")
+    print(f"  {'skill':<32} {'invocable':<10} {'tools'}")
+    for row in rows:
+        inv = row["user_invocable"] or "-"
+        tools = ",".join(row["tools"]) or "(none declared)"
+        print(f"  {row['name']:<32} {inv:<10} {tools}")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -260,23 +358,97 @@ def print_json(findings: list[Finding]) -> None:
     print(json.dumps(report, indent=2))
 
 
+# SARIF severity maps to GitHub Advanced Security Code Scanning levels.
+_SARIF_LEVEL = {"HIGH": "error", "WARN": "warning", "INFO": "note"}
+
+
+def _sarif_rules(findings: list[Finding]) -> list[dict]:
+    """Build the tool.driver.rules array from unique (severity, description) pairs."""
+    seen: dict[str, dict] = {}
+    for f in findings:
+        rule_id = f"{f.severity}-{hash(f.description) & 0xFFFFFFFF:08x}"
+        if rule_id in seen:
+            continue
+        seen[rule_id] = {
+            "id": rule_id,
+            "name": f.description.split(" — ")[0].replace(" ", "-").lower()[:64],
+            "shortDescription": {"text": f.description},
+            "defaultConfiguration": {"level": _SARIF_LEVEL.get(f.severity, "note")},
+        }
+    return list(seen.values())
+
+
+def print_sarif(findings: list[Finding], toolkit_root: Path) -> None:
+    """Print SARIF 2.1.0 report for GitHub Code Scanning ingestion."""
+    rules = _sarif_rules(findings)
+    rule_index = {r["shortDescription"]["text"]: i for i, r in enumerate(rules)}
+    results = []
+    for f in findings:
+        idx = rule_index.get(f.description, 0)
+        rule_id = rules[idx]["id"] if rules else "unknown"
+        try:
+            rel = str(Path(f.file).resolve().relative_to(toolkit_root.resolve()))
+        except ValueError:
+            rel = f.file
+        results.append({
+            "ruleId": rule_id,
+            "ruleIndex": idx,
+            "level": _SARIF_LEVEL.get(f.severity, "note"),
+            "message": {"text": f.description},
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {"uri": rel},
+                    "region": {"startLine": max(1, f.line)},
+                }
+            }],
+        })
+    sarif = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "ai-toolkit-audit-skills",
+                    "informationUri": "https://github.com/softspark/ai-toolkit",
+                    "rules": rules,
+                }
+            },
+            "results": results,
+        }],
+    }
+    print(json.dumps(sarif, indent=2))
+
+
 def main() -> None:
     args = sys.argv[1:]
     toolkit_root = default_toolkit_dir
     json_mode = False
+    sarif_mode = False
+    permissions_mode = False
     ci_mode = False
 
     for arg in args:
         if arg == "--json":
             json_mode = True
+        elif arg == "--sarif":
+            sarif_mode = True
+        elif arg == "--permissions":
+            permissions_mode = True
         elif arg == "--ci":
             ci_mode = True
         elif not arg.startswith("-"):
             toolkit_root = Path(arg)
 
+    if permissions_mode:
+        rows = collect_permissions(toolkit_root)
+        print_permissions(rows, json_mode=json_mode)
+        return
+
     findings = audit(toolkit_root)
 
-    if json_mode:
+    if sarif_mode:
+        print_sarif(findings, toolkit_root)
+    elif json_mode:
         print_json(findings)
     else:
         print_text(findings)

package/scripts/config_resolver.py

@@ -302,9 +302,12 @@ def _extract_tarball(tarball: Path, dest: Path) -> None:
     """Extract npm tarball (which has a package/ prefix) to dest.
 
     Validates that extracted paths stay within dest to prevent path traversal.
-    Rejects symlinks and absolute paths.
+    Rejects symlinks and absolute paths. Uses tarfile filter="data" on 3.12+
+    as defense in depth (Python 3.14 will require it).
     """
     dest_resolved = dest.resolve()
+    # filter="data" landed in 3.12 and becomes the default in 3.14
+    supports_filter = sys.version_info >= (3, 12)
     with tarfile.open(tarball, "r:gz") as tf:
         for member in tf.getmembers():
             # npm tarballs have a "package/" prefix
@@ -320,7 +323,10 @@ def _extract_tarball(tarball: Path, dest: Path) -> None:
             target = (dest / member.name).resolve()
             if not str(target).startswith(str(dest_resolved)):
                 continue
-            tf.extract(member, dest)
+            if supports_filter:
+                tf.extract(member, dest, filter="data")
+            else:
+                tf.extract(member, dest)
 
 
 def _extract_version_from_tarball(filename: str, package_name: str) -> str:

package/scripts/hook_sources.py

@@ -10,6 +10,7 @@ Stdlib-only — no external dependencies.
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import sys
@@ -78,17 +79,43 @@ def save_sources(hooks_dir: Path | None = None,
 # CRUD
 # ---------------------------------------------------------------------------
 
-def register_url_source(hooks_dir: Path | None, hook_name: str, url: str) -> None:
-    """Add or update a URL source entry."""
+def register_url_source(
+    hooks_dir: Path | None,
+    hook_name: str,
+    url: str,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a URL source entry.
+
+    When ``content`` is supplied, its sha256 is persisted. If a previous
+    sha256 exists and differs from the new one, a warning is printed
+    (and the process fails with exit 2 when ``AI_TOOLKIT_STRICT_PIN=1``).
+    """
     import re
     if not hook_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", hook_name):
         raise ValueError(f"Invalid hook name: {hook_name!r}")
     hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
     sources = load_sources(hooks_dir)
-    sources[hook_name] = {
+    entry: dict[str, Any] = {
         "url": url,
         "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
     }
+    if content is not None:
+        new_hash = hashlib.sha256(content).hexdigest()
+        prev = sources.get(hook_name) or {}
+        prev_hash = prev.get("sha256")
+        if prev_hash and prev_hash != new_hash:
+            msg = (
+                f"  CHECKSUM CHANGED: hook '{hook_name}' sha256 "
+                f"{prev_hash[:12]}... -> {new_hash[:12]}..."
+            )
+            print(msg)
+            if os.environ.get("AI_TOOLKIT_STRICT_PIN") == "1":
+                raise SystemExit(
+                    f"Refusing to update '{hook_name}' under AI_TOOLKIT_STRICT_PIN=1."
+                )
+        entry["sha256"] = new_hash
+    sources[hook_name] = entry
     save_sources(hooks_dir, sources)
 
 

package/scripts/inject_hook_cli.py

@@ -284,7 +284,7 @@ def _fetch_and_cache(url: str, source: str) -> str:
 
     cached_path = EXTERNAL_HOOKS_DIR / f"{source}.json"
     cached_path.write_bytes(data)
-    register_url_source(None, source, url)
+    register_url_source(None, source, url, content=data)
 
     return str(cached_path)
 

package/scripts/install_steps/ai_tools.py

@@ -194,7 +194,11 @@ def inject_with_rules(
     else:
         cmd = ["bash", str(scripts_dir / generator_script)]
 
-    result = subprocess.run(cmd, capture_output=True, text=True)
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+    except subprocess.TimeoutExpired:
+        print(f"  ERROR: {generator_script} timed out after 120s")
+        return
     if result.returncode != 0:
         print(f"  ERROR: {generator_script} failed: {result.stderr.strip()}")
         return
@@ -240,7 +244,11 @@ def run_script(script_name: str, *args: str, capture: bool = False) -> str:
         cmd = ["python3", str(scripts_dir / py_name), *args]
     else:
         cmd = ["bash", str(scripts_dir / script_name), *args]
-    result = subprocess.run(cmd, capture_output=capture, text=True)
+    try:
+        result = subprocess.run(cmd, capture_output=capture, text=True, timeout=120)
+    except subprocess.TimeoutExpired:
+        print(f"  ERROR: {script_name} timed out after 120s")
+        return ""
     return result.stdout if capture else ""
 
 

package/scripts/install_steps/hooks.py

@@ -64,7 +64,7 @@ def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
 
 def _run_merge_hooks(action: str, *args: str) -> None:
     cmd = ["python3", str(toolkit_dir / "scripts" / "merge-hooks.py"), action, *args]
-    subprocess.run(cmd, check=True)
+    subprocess.run(cmd, check=True, timeout=120)
 
 
 def _install_output_styles(claude_dir: Path) -> None:

package/scripts/install_steps/markers.py

@@ -88,7 +88,7 @@ def _refresh_url_rules(rules_dir: Path) -> None:
         try:
             data = fetch_url(url)
             rule_file.write_bytes(data)
-            register_url_source(rules_dir, rule_name, url)
+            register_url_source(rules_dir, rule_name, url, content=data)
             print(f"  Refreshed: {rule_name} (from {url})")
         except Exception as exc:
             if rule_file.is_file():
@@ -124,7 +124,7 @@ def refresh_url_hooks(target_dir: str | None = None) -> None:
             # Validate JSON before caching
             json.loads(data)
             cached_file.write_bytes(data)
-            register_url_source(None, hook_name, url)
+            register_url_source(None, hook_name, url, content=data)
             print(f"  Refreshed: {hook_name} (from {url})")
         except Exception as exc:
             if cached_file.is_file():

package/scripts/rule_sources.py

@@ -10,6 +10,7 @@ Stdlib-only — no external dependencies.
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import sys
@@ -79,17 +80,43 @@ def save_sources(rules_dir: Path | None = None,
 # CRUD
 # ---------------------------------------------------------------------------
 
-def register_url_source(rules_dir: Path | None, rule_name: str, url: str) -> None:
-    """Add or update a URL source entry."""
+def register_url_source(
+    rules_dir: Path | None,
+    rule_name: str,
+    url: str,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a URL source entry.
+
+    When ``content`` is supplied, its sha256 is persisted. If a previous
+    sha256 exists and differs from the new one, a warning is printed
+    (and the process fails with exit 2 when ``AI_TOOLKIT_STRICT_PIN=1``).
+    """
     import re
     if not rule_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", rule_name):
         raise ValueError(f"Invalid rule name: {rule_name!r}")
     rules_dir = rules_dir or RULES_DIR
     sources = load_sources(rules_dir)
-    sources[rule_name] = {
+    entry: dict[str, Any] = {
         "url": url,
         "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
     }
+    if content is not None:
+        new_hash = hashlib.sha256(content).hexdigest()
+        prev = sources.get(rule_name) or {}
+        prev_hash = prev.get("sha256")
+        if prev_hash and prev_hash != new_hash:
+            msg = (
+                f"  CHECKSUM CHANGED: rule '{rule_name}' sha256 "
+                f"{prev_hash[:12]}... -> {new_hash[:12]}..."
+            )
+            print(msg)
+            if os.environ.get("AI_TOOLKIT_STRICT_PIN") == "1":
+                raise SystemExit(
+                    f"Refusing to update '{rule_name}' under AI_TOOLKIT_STRICT_PIN=1."
+                )
+        entry["sha256"] = new_hash
+    sources[rule_name] = entry
     save_sources(rules_dir, sources)