@softspark/ai-toolkit 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.4.1 — Codex Global Install, Security Hardening & Editor Tracking (2026-04-15)
+
+### Added
+- **Codex hook propagation** — `inject-hook` auto-propagates Codex-compatible events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) to `~/.codex/hooks.json`. `remove-hook` cleans both targets.
+- **Global editor tracking** — `ai-toolkit install --editors codex` installs editors globally (opt-in). Tracked in `state.json`, auto-refreshed on `update`. Default: Claude only.
+- **Per-project editor tracking** — `install --local --editors` records editors in `projects.json`. `update` re-installs saved editors per project.
+- **Auto-propagation** — `add-rule`, `remove-rule`, `mcp add` auto-propagate to globally installed editors via `propagate_global.py`.
+- **Doctor Check 9** — URL hook sources health check with `--fix` re-fetch support.
+
+### Fixed
+- **Tarball path traversal** — `_extract_tarball` rejects symlinks, absolute paths, and paths escaping dest directory.
+- **Git clone URL validation** — `_resolve_git` enforces HTTPS-only, rejects `file://`, `ssh://`.
+- **`dr.error()` crash** — `DiagResult` has no `error()` method; fixed to `dr.fail()`.
+- **`refresh_url_hooks` missing timestamp update** — now calls `register_url_source` after re-fetch.
+- **Defense-in-depth name validation** — `register_url_source()` rejects path traversal chars in both `hook_sources` and `rule_sources`.
+- **Unused `execSync` import** — removed from CLI entry point.
+- **URL truncation detection** — `url_fetch.py` raises `ValueError` when response exceeds 10MB.
+- **MCP templates path** — corrected `app/plugins/mcp-templates/` → `app/mcp-templates/` in ARCHITECTURE docs.
+- **MCP templates header count** — corrected 25 → 26 in `app/ARCHITECTURE.md`.
+
+---
+
 ## v2.4.0 — URL Hook Injection & Karpathy Coding Rules (2026-04-15)
 
 ### Added

package/README.md

@@ -6,16 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-92-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-613%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-618%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.4.0
+## What's New in v2.4.1
 
-- **URL hook injection** — `ai-toolkit inject-hook https://...` with auto-refresh on every update (mirrors `add-rule` URL support)
-- **Shared URL fetch** — extracted `url_fetch.py` for reuse across rule and hook URL sources
-- **Surgical Changes rule** — orphan cleanup protocol and "match existing style" in `common/coding-style.md`
-- **Goal-Driven Execution rule** — `step → verify: check` pattern for multi-step tasks
+- **Global editor tracking** — `ai-toolkit install --editors codex` installs Codex globally, tracked in `state.json`, auto-refreshed on `update`
+- **Codex hook propagation** — `inject-hook` auto-propagates to `~/.codex/hooks.json` for Codex-compatible events
+- **Auto-propagation** — `add-rule`, `remove-rule`, `mcp add` auto-propagate to all globally installed editors
+- **Security hardening** — tarball path traversal fix, git URL scheme validation, defense-in-depth name validation
+- **Doctor Check 9** — URL hook sources health check with `--fix` re-fetch support
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -142,7 +143,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (613 tests)
+├── tests/               # Bats test suite (618 tests)
 └── CHANGELOG.md
 ```
 

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.4.0",
+  "version": "2.4.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -301,8 +301,8 @@ Lead Session (You)
 
 ## Extension Points
 
-### MCP Templates (25)
-`app/plugins/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+### MCP Templates (26)
+`app/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.

package/bin/ai-toolkit.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-const { execFileSync, spawnSync, execSync } = require('child_process');
+const { execFileSync, spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
@@ -151,6 +151,23 @@ function run(script, args = [], opts = {}) {
   }
 }
 
+/**
+ * Propagate changes to globally installed editors (from state.json).
+ * Silently skips if no global editors are configured.
+ * @param {...string} flags - Flags to pass: --rules, --hooks, --mcp
+ */
+function propagateGlobal(...flags) {
+  const result = spawnSync('python3', [scriptPath('propagate_global.py'), ...flags], {
+    stdio: 'inherit',
+    cwd: CWD,
+    env: { ...process.env },
+  });
+  // Non-fatal — propagation failure shouldn't block the primary operation
+  if (result.status !== 0) {
+    console.error('Warning: global editor propagation had issues (non-fatal)');
+  }
+}
+
 /**
  * Generic dispatcher for SCRIPT_COMMANDS entries.
  * Resolves the script path and selects the correct cwd.
@@ -331,6 +348,7 @@ function handleRemoveRule(args) {
   }
   const targetDir = args[1] || process.env.HOME;
   run(scriptPath('remove_rule.py'), [ruleName, targetDir]);
+  propagateGlobal('--rules');
 }
 
 /**
@@ -345,9 +363,14 @@ function handleAddRule(args) {
   }
   // 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 absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);
+  propagateGlobal('--rules');
 }
 
 /**
@@ -392,6 +415,10 @@ function handleMcp(args) {
     process.exit(1);
   }
   run(scriptPath('mcp_manager.py'), args);
+  // After `mcp add`, propagate to global editors
+  if (args[0] === 'add') {
+    propagateGlobal('--mcp');
+  }
 }
 
 /**

package/kb/reference/architecture-overview.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [architecture, overview, design, structure]
 version: "1.4.4"
 created: "2026-03-23"
-last_updated: "2026-04-13"
+last_updated: "2026-04-15"
 description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -335,7 +335,7 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 ## Extension Points
 
 ### MCP Templates
-`app/plugins/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+`app/mcp-templates/` contains 26 ready-to-use MCP server config templates. Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules
 `app/rules/` provides language-specific rule files covering 13 languages (TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, common). Auto-detected from project files via `--auto-detect` or selectable with `--modules rules-<lang>`. See README.md for current count.

package/kb/reference/cli-reference.md

@@ -4,7 +4,7 @@ category: reference
 service: ai-toolkit
 tags: [cli, commands, reference, install, update, plugin, mcp]
 created: "2026-04-13"
-last_updated: "2026-04-13"
+last_updated: "2026-04-15"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 

package/kb/reference/codex-cli-compatibility.md

@@ -107,6 +107,10 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
 `SubagentStart`, `SubagentStop`, `PreCompact`, `SessionEnd`, and
 `Notification` are not available in `.codex/hooks.json`.
 
+`inject-hook` automatically propagates Codex-compatible events to
+`~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
+`remove-hook` cleans both Claude and Codex targets.
+
 ## Behavioral Limits
 
 Codex wrappers preserve workflow intent, but not every Claude runtime behavior

package/kb/reference/extension-api.md

@@ -103,6 +103,8 @@ npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hoo
 
 **Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks. Only HTTPS URLs are accepted.
 
+**Codex propagation:** Codex-compatible events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) are automatically propagated to `~/.codex/hooks.json`. Non-Codex events are silently skipped. No extra flags needed.
+
 ## remove-hook
 
 Strips all hook entries from `~/.claude/settings.json` that carry a given `_source` tag. If the hook was URL-sourced, also unregisters the URL from `sources.json` and removes the cached file.

package/llms-full.txt

@@ -5380,6 +5380,10 @@ This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
 `SubagentStart`, `SubagentStop`, `PreCompact`, `SessionEnd`, and
 `Notification` are not available in `.codex/hooks.json`.
 
+`inject-hook` automatically propagates Codex-compatible events to
+`~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
+`remove-hook` cleans both Claude and Codex targets.
+
 ## Behavioral Limits
 
 Codex wrappers preserve workflow intent, but not every Claude runtime behavior
@@ -6634,6 +6638,8 @@ npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hoo
 
 **Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks. Only HTTPS URLs are accepted.
 
+**Codex propagation:** Codex-compatible events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) are automatically propagated to `~/.codex/hooks.json`. Non-Codex events are silently skipped. No extra flags needed.
+
 ## remove-hook
 
 Strips all hook entries from `~/.claude/settings.json` that carry a given `_source` tag. If the hook was URL-sourced, also unregisters the URL from `sources.json` and removes the cached file.

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",

package/scripts/config_resolver.py

@@ -299,14 +299,28 @@ def _find_cached_npm(cache_dir: Path) -> Path | None:
 
 
 def _extract_tarball(tarball: Path, dest: Path) -> None:
-    """Extract npm tarball (which has a package/ prefix) to dest."""
+    """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.
+    """
+    dest_resolved = dest.resolve()
     with tarfile.open(tarball, "r:gz") as tf:
         for member in tf.getmembers():
             # npm tarballs have a "package/" prefix
-            if member.name.startswith("package/"):
-                member.name = member.name[len("package/"):]
-                if member.name:  # skip empty (the "package/" dir itself)
-                    tf.extract(member, dest)
+            if not member.name.startswith("package/"):
+                continue
+            member.name = member.name[len("package/"):]
+            if not member.name:  # skip empty (the "package/" dir itself)
+                continue
+            # Reject symlinks and absolute paths
+            if member.issym() or member.islnk() or member.name.startswith("/"):
+                continue
+            # Path traversal protection
+            target = (dest / member.name).resolve()
+            if not str(target).startswith(str(dest_resolved)):
+                continue
+            tf.extract(member, dest)
 
 
 def _extract_version_from_tarball(filename: str, package_name: str) -> str:
@@ -332,6 +346,10 @@ def _resolve_git(
 ) -> BaseConfig:
     """Resolve from git URL (git+https://...)."""
     url = source.removeprefix("git+")
+    if not url.startswith("https://"):
+        raise ConfigResolverError(
+            f"Only HTTPS git URLs are supported (got: {url.split('://')[0]}://)"
+        )
     cache_key = hashlib.sha256(url.encode()).hexdigest()[:16]
     cache_dir = _cache_root() / "git" / cache_key
 

package/scripts/doctor.py

@@ -10,6 +10,7 @@ Checks:
   6. Planned assets
   7. Benchmark freshness
   8. Stale rules
+  9. URL hook sources
 
 Exit codes:
   0  all checks pass
@@ -27,7 +28,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir
-from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR
+from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR, EXTERNAL_HOOKS_DIR as _EXTERNAL_HOOKS_DIR
 
 
 # ---------------------------------------------------------------------------
@@ -37,6 +38,7 @@ from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR
 CLAUDE_DIR = Path.home() / ".claude"
 HOOKS_DIR = _HOOKS_DIR
 RULES_DIR = _RULES_DIR
+EXTERNAL_HOOKS_DIR = _EXTERNAL_HOOKS_DIR
 BENCHMARK_DASHBOARD = toolkit_dir / "benchmarks" / "ecosystem-dashboard.json"
 
 VALID_EVENTS = frozenset({
@@ -465,6 +467,75 @@ def check_stale_rules(dr: DiagResult, fix_mode: bool) -> None:
         dr.ok("All rules healthy")
 
 
+# ---------------------------------------------------------------------------
+# Check 9: URL Hook Sources
+# ---------------------------------------------------------------------------
+
+def check_url_hooks(dr: DiagResult, fix_mode: bool) -> None:
+    """Check URL-sourced hook cache integrity."""
+    print()
+    print("## 9. URL Hook Sources")
+
+    sources_file = EXTERNAL_HOOKS_DIR / "sources.json"
+    if not sources_file.is_file():
+        dr.skip("No URL hook sources registered")
+        return
+
+    try:
+        with open(sources_file, encoding="utf-8") as f:
+            data = json.load(f)
+        sources = data.get("hooks", {})
+    except (json.JSONDecodeError, OSError) as exc:
+        dr.fail(f"Corrupt sources.json: {exc}")
+        return
+
+    if not sources:
+        dr.ok("No URL hook sources registered")
+        return
+
+    issues = 0
+    for name, entry in sources.items():
+        cached = EXTERNAL_HOOKS_DIR / f"{name}.json"
+        url = entry.get("url", "")
+
+        if not cached.is_file():
+            dr.warn(f"Missing cached file for '{name}' ({url})")
+            issues += 1
+            if fix_mode:
+                try:
+                    from url_fetch import fetch_url
+                    content = fetch_url(url)
+                    json.loads(content)  # validate
+                    EXTERNAL_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+                    cached.write_bytes(content)
+                    print(f"    FIXED: re-fetched {name}")
+                except Exception as exc:
+                    print(f"    Could not re-fetch: {exc}")
+            continue
+
+        # Validate cached file is valid JSON with hooks key
+        try:
+            with open(cached, encoding="utf-8") as f:
+                hook_data = json.load(f)
+            if "hooks" not in hook_data:
+                dr.warn(f"Cached file '{name}' missing 'hooks' key")
+                issues += 1
+            else:
+                dr.ok(f"{name} ({url})")
+        except json.JSONDecodeError:
+            dr.warn(f"Corrupt cached file: {cached}")
+            issues += 1
+            if fix_mode:
+                try:
+                    from url_fetch import fetch_url
+                    content = fetch_url(url)
+                    json.loads(content)
+                    cached.write_bytes(content)
+                    print(f"    FIXED: re-fetched {name}")
+                except Exception as exc:
+                    print(f"    Could not re-fetch: {exc}")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -486,6 +557,7 @@ def main() -> None:
     check_planned_assets(dr)
     check_benchmark_freshness(dr)
     check_stale_rules(dr, fix_mode)
+    check_url_hooks(dr, fix_mode)
 
     # Summary
     print("========================")

package/scripts/hook_sources.py

@@ -80,6 +80,9 @@ def save_sources(hooks_dir: Path | None = None,
 
 def register_url_source(hooks_dir: Path | None, hook_name: str, url: str) -> None:
     """Add or update a URL source entry."""
+    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] = {

package/scripts/inject_hook_cli.py

@@ -49,6 +49,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 # Protected source tag -- this CLI must never touch ai-toolkit's own entries.
 PROTECTED_SOURCE = "ai-toolkit"
 
+# Codex CLI supports only these 5 hook events.
+CODEX_EVENTS = {"SessionStart", "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"}
+
 
 # ---------------------------------------------------------------------------
 # JSON helpers (same style as merge-hooks.py)
@@ -179,6 +182,70 @@ def merge_hooks(new_hooks: dict, existing_hooks: dict, source: str) -> dict:
     return merged
 
 
+# ---------------------------------------------------------------------------
+# Codex propagation
+# ---------------------------------------------------------------------------
+
+def _codex_hooks_path(target_dir: str) -> Path:
+    """Return the global Codex hooks.json path."""
+    return Path(target_dir) / ".codex" / "hooks.json"
+
+
+def _filter_codex_events(hooks: dict) -> dict:
+    """Keep only events supported by Codex CLI."""
+    return {event: entries for event, entries in hooks.items()
+            if event in CODEX_EVENTS}
+
+
+def _inject_codex(tagged_hooks: dict, source: str, target_dir: str) -> None:
+    """Propagate hook entries to ~/.codex/hooks.json (Codex global layer).
+
+    Only events in CODEX_EVENTS are propagated. Non-Codex events are silently
+    skipped.
+    """
+    codex_hooks = _filter_codex_events(tagged_hooks)
+    if not codex_hooks:
+        return
+
+    codex_path = _codex_hooks_path(target_dir)
+    codex_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict = {}
+    if codex_path.is_file():
+        try:
+            data = load_json(str(codex_path))
+            existing = data.get("hooks", {})
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    merged = merge_hooks(codex_hooks, existing, source)
+    save_json(str(codex_path), {"hooks": merged})
+    events = ", ".join(sorted(codex_hooks.keys()))
+    print(f"Propagated to Codex: {codex_path} (events: {events})")
+
+
+def _remove_codex(source_name: str, target_dir: str) -> None:
+    """Remove hook entries from ~/.codex/hooks.json."""
+    codex_path = _codex_hooks_path(target_dir)
+    if not codex_path.is_file():
+        return
+
+    try:
+        data = load_json(str(codex_path))
+    except (json.JSONDecodeError, OSError):
+        return
+
+    existing = data.get("hooks", {})
+    cleaned = strip_source(existing, source_name)
+
+    if cleaned:
+        save_json(str(codex_path), {"hooks": cleaned})
+    else:
+        save_json(str(codex_path), {"hooks": {}})
+
+    print(f"Removed '{source_name}' from Codex: {codex_path}")
+
+
 # ---------------------------------------------------------------------------
 # CLI actions
 # ---------------------------------------------------------------------------
@@ -213,7 +280,7 @@ def _fetch_and_cache(url: str, source: str) -> str:
         sys.exit(2)
 
     if "hooks" not in parsed:
-        print(f"Warning: no 'hooks' key found in URL response", file=sys.stderr)
+        print("Warning: no 'hooks' key found in URL response", file=sys.stderr)
 
     cached_path = EXTERNAL_HOOKS_DIR / f"{source}.json"
     cached_path.write_bytes(data)
@@ -310,6 +377,9 @@ def inject(hooks_file: str, target_dir: str, source_override: str = "") -> None:
     save_json(str(settings_path), settings)
     print(f"Injected hooks from '{source}' into {settings_path}")
 
+    # Propagate Codex-compatible events to ~/.codex/hooks.json
+    _inject_codex(tagged, source, target_dir)
+
 
 def remove(source_name: str, target_dir: str) -> None:
     """Remove all hook entries tagged with *source_name*.
@@ -354,6 +424,9 @@ def remove(source_name: str, target_dir: str) -> None:
     save_json(str(settings_path), settings)
     print(f"Removed hooks with source '{source_name}' from {settings_path}")
 
+    # Remove from Codex global hooks
+    _remove_codex(source_name, target_dir)
+
     # Unregister URL source if present
     try:
         from hook_sources import unregister_source

package/scripts/install.py

@@ -54,7 +54,10 @@ from install_steps.install_state import (
     record_install,
     get_installed_modules,
     get_installed_profile,
+    get_global_editors,
+    record_global_editors,
     print_status,
+    GLOBAL_CAPABLE_EDITORS,
 )
 from install_steps.detect_language import detect_languages
 from install_steps.project_registry import register_project
@@ -708,17 +711,31 @@ def main() -> None:
             profile = cfg["profile"]
 
         lang_modules = [m for m in (resolved_modules or []) if m.startswith("rules-")]
-        editors_arg: str = cfg["editors"]
+        local_editors_arg: str = cfg["editors"]
         install_local_project(rules_dir, dry_run, reset, lang_modules or None,
-                              editors=editors_arg,
+                              editors=local_editors_arg,
                               merged_config=merged_config)
+        installed_eds: list[str] = []  # local install doesn't track global editors
         install_strict_git_hooks(profile, local, dry_run)
     else:
         # Global install
         print_banner(target_dir, rules_dir, profile, only, skip, dry_run,
                      modules=resolved_modules)
         install_claude_code(target_dir, hooks_scripts_dir, rules_dir, only, skip, dry_run)
-        install_ai_tools(target_dir, rules_dir, only, skip, dry_run)
+
+        # Determine global editors: --editors flag > state > default (none)
+        editors_arg: str = cfg["editors"]
+        if editors_arg:
+            if editors_arg == "all":
+                global_eds = list(GLOBAL_CAPABLE_EDITORS)
+            else:
+                global_eds = [e.strip() for e in editors_arg.split(",") if e.strip()]
+        else:
+            # On update: use editors from state; on fresh install: none
+            global_eds = get_global_editors() or None
+
+        installed_eds = install_ai_tools(target_dir, rules_dir, dry_run,
+                                         editors=global_eds)
         install_persona(target_dir, persona, dry_run)
         install_strict_git_hooks(profile, local, dry_run)
 
@@ -749,6 +766,10 @@ def main() -> None:
             extends_info=extends_info,
         )
 
+        # Record global editors (only for global install, not --local)
+        if not local and installed_eds:
+            record_global_editors(installed_eds)
+
         # Register project in global registry (for `ai-toolkit update` propagation)
         # Skipped when called from update_projects.py (--skip-register) to avoid
         # concurrent writes to projects.json during parallel updates.
@@ -756,10 +777,20 @@ def main() -> None:
             extends_source = ""
             if extends_info:
                 extends_source = extends_info.get("source", "")
+            # Determine editors to record for this project
+            local_eds_for_registry: list[str] | None = None
+            if local and local_editors_arg:
+                if local_editors_arg == "all":
+                    from install_steps.ai_tools import ALL_EDITORS
+                    local_eds_for_registry = list(ALL_EDITORS)
+                else:
+                    local_eds_for_registry = [e.strip() for e in local_editors_arg.split(",") if e.strip()]
+
             is_new = register_project(
                 project_dir,
                 profile=profile or "standard",
                 extends=extends_source,
+                editors=local_eds_for_registry,
             )
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")

package/scripts/install_steps/ai_tools.py

@@ -19,50 +19,113 @@ from injection import (
 
 
 def install_ai_tools(target_dir: Path, rules_dir: Path,
-                     only: str, skip: str, dry_run: bool) -> None:
-    """Install Cursor, Windsurf, Gemini global configs."""
+                     dry_run: bool,
+                     editors: list[str] | None = None) -> list[str]:
+    """Install global editor configs.
+
+    Args:
+        editors: Explicit list of editors to install globally. If None,
+                 uses DEFAULT_GLOBAL_EDITORS (empty = Claude only).
+
+    Returns:
+        List of editors that were actually installed (for state tracking).
+    """
+    from install_steps.install_state import DEFAULT_GLOBAL_EDITORS, GLOBAL_CAPABLE_EDITORS
+
+    if editors is None:
+        eds = set(DEFAULT_GLOBAL_EDITORS)
+    else:
+        eds = set(editors)
+
+    # Filter to only globally-capable editors
+    eds = eds & set(GLOBAL_CAPABLE_EDITORS)
+
+    if not eds:
+        return []
+
     print()
     print("## Other AI Tools (global)")
     print()
 
-    if should_install("cursor", only, skip):
+    installed: list[str] = []
+
+    # Editors are opt-in via --editors, not filtered by --only/--skip (those
+    # control Claude components like agents, hooks, rules).  If an editor is
+    # in the requested set, install it unconditionally.
+
+    if "cursor" in eds:
         cursor_file = target_dir / ".cursor" / "rules"
         if dry_run:
             print("  Would inject: ~/.cursor/rules")
         else:
             inject_with_rules("generate-cursor-rules.sh", cursor_file, rules_dir)
-    else:
-        print("  Skipped: cursor")
+        installed.append("cursor")
 
-    if should_install("windsurf", only, skip):
+    if "windsurf" in eds:
         windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
         if dry_run:
             print("  Would inject: ~/.codeium/windsurf/memories/global_rules.md")
         else:
             inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
-    else:
-        print("  Skipped: windsurf")
+        installed.append("windsurf")
 
-    if should_install("gemini", only, skip):
+    if "gemini" in eds:
         gemini_file = target_dir / ".gemini" / "GEMINI.md"
         if dry_run:
             print("  Would inject: ~/.gemini/GEMINI.md")
         else:
             inject_with_rules("generate-gemini.sh", gemini_file, rules_dir)
-    else:
-        print("  Skipped: gemini")
+        installed.append("gemini")
 
-    if should_install("augment", only, skip):
+    if "augment" in eds:
         augment_file = target_dir / ".augment" / "rules" / "ai-toolkit.md"
         if dry_run:
             print("  Would inject: ~/.augment/rules/ai-toolkit.md")
         else:
             inject_with_rules("generate-augment.sh", augment_file, rules_dir)
-    else:
-        print("  Skipped: augment")
+        installed.append("augment")
+
+    if "codex" in eds:
+        if dry_run:
+            print("  Would inject: ~/AGENTS.md, ~/.agents/, ~/.codex/hooks.json")
+        else:
+            _install_codex_global(target_dir, rules_dir)
+        installed.append("codex")
 
     print()
-    print("  Note: Copilot, Cline, Roo Code, and Aider have no global config -- use 'ai-toolkit install --local' per project")
+    print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
+    print("  Note: Copilot, Cline, Roo Code, Aider, Antigravity have no global config -- use 'ai-toolkit install --local' per project")
+
+    return installed
+
+
+def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
+    """Install Codex at the global level (~/ layer).
+
+    Creates:
+      - ~/AGENTS.md (marker injection with rules)
+      - ~/.agents/rules/*.md (directory-based rules)
+      - ~/.agents/skills/* (skill symlinks)
+      - ~/.codex/hooks.json (lifecycle hooks)
+    """
+    inject_with_rules(
+        "generate_codex.py",
+        target_dir / "AGENTS.md",
+        rules_dir,
+    )
+
+    from generate_codex_rules import generate as gen_codex_rules
+    gen_codex_rules(
+        target_dir,
+        rules_dir=rules_dir,
+        managed_scopes=("standard", "custom"),
+    )
+
+    from generate_codex_hooks import generate as gen_codex_hooks
+    gen_codex_hooks(target_dir)
+    print("  Created: ~/.codex/hooks.json")
+
+    _install_codex_skills(target_dir)
 
 
 def inject_with_rules(

package/scripts/install_steps/install_state.py

@@ -85,6 +85,27 @@ def remove_mcp_template(name: str) -> None:
     save_state(state)
 
 
+# Default global install: Claude only — no other editors unless --editors is used
+DEFAULT_GLOBAL_EDITORS: list[str] = []
+
+# All editors that support global install (opt-in via --editors)
+GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "windsurf"]
+
+
+def get_global_editors() -> list[str]:
+    """Return list of globally installed editor names from state."""
+    state = load_state()
+    editors = state.get("global_editors", [])
+    return editors if isinstance(editors, list) else []
+
+
+def record_global_editors(editors: list[str]) -> None:
+    """Record which editors are installed globally in state.json."""
+    state = load_state()
+    state["global_editors"] = sorted(set(editors))
+    save_state(state)
+
+
 def _now_iso() -> str:
     """Return current UTC time in ISO 8601 format."""
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -163,6 +184,10 @@ def print_status() -> None:
         langs = [m.replace("rules-", "") for m in detected]
         print(f"  Detected:   {', '.join(langs)}")
 
+    editors = state.get("global_editors", [])
+    if editors:
+        print(f"  Editors:    {', '.join(editors)}")
+
     mcp = state.get("mcp_templates", [])
     if mcp:
         print(f"  MCP:        {', '.join(mcp)}")

package/scripts/install_steps/markers.py

@@ -105,7 +105,7 @@ def refresh_url_hooks(target_dir: str | None = None) -> None:
     Called during ``ai-toolkit update`` to keep URL-sourced hooks current.
     On fetch failure, warns and keeps the cached version.
     """
-    from hook_sources import get_url_hooks
+    from hook_sources import get_url_hooks, register_url_source
     from paths import EXTERNAL_HOOKS_DIR
     from url_fetch import fetch_url
     import json
@@ -124,6 +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)
             print(f"  Refreshed: {hook_name} (from {url})")
         except Exception as exc:
             if cached_file.is_file():

package/scripts/install_steps/project_registry.py

@@ -130,11 +130,17 @@ def register_project(
     project_path: str | Path,
     profile: str = "",
     extends: str = "",
+    editors: list[str] | None = None,
 ) -> bool:
     """Register a project directory. Returns True if newly added, False if updated.
 
     Idempotent — updates existing entry if path already registered.
     Uses file lock to prevent concurrent read-modify-write races.
+
+    Args:
+        editors: List of editors installed locally (e.g. ["codex", "cursor"]).
+                 If provided, replaces the stored editors list. If None, keeps
+                 existing editors (or empty for new projects).
     """
     project_path = str(Path(project_path).resolve())
 
@@ -153,6 +159,8 @@ def register_project(
                 elif "extends" in p and not extends:
                     # Clear extends if project no longer uses it
                     pass
+                if editors is not None:
+                    p["editors"] = sorted(set(editors))
                 save_registry(projects)
                 return False
 
@@ -163,6 +171,7 @@ def register_project(
             "last_updated": now,
             "profile": profile or "standard",
             "extends": extends or "",
+            "editors": sorted(set(editors)) if editors else [],
         })
         save_registry(projects)
         return True

package/scripts/propagate_global.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Propagate rules, hooks, and MCP configs to all globally installed editors.
+
+Called automatically after inject-rule, inject-hook, add-rule, remove-rule,
+and mcp add to keep global editor configs in sync.
+
+Usage:
+    propagate_global.py [--rules] [--hooks] [--mcp]
+
+Flags (can combine):
+    --rules   Re-inject registered rules into global editor configs
+    --hooks   Re-inject external hooks into Codex global hooks.json
+    --mcp     Sync MCP templates to global editor MCP configs
+
+With no flags, propagates rules (the most common case).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def propagate_rules() -> None:
+    """Re-inject registered rules into all global editors from state."""
+    from paths import RULES_DIR
+    from install_steps.install_state import get_global_editors
+
+    editors = get_global_editors()
+    if not editors:
+        return
+
+    target_dir = Path.home()
+    rules_dir = RULES_DIR
+
+    from install_steps.ai_tools import install_ai_tools
+    print("Propagating rules to global editors...")
+    install_ai_tools(target_dir, rules_dir, dry_run=False, editors=editors)
+
+
+def propagate_hooks() -> None:
+    """Re-inject URL-sourced hooks into Codex global hooks.json."""
+    from install_steps.install_state import get_global_editors
+
+    editors = get_global_editors()
+    if "codex" not in editors:
+        return
+
+    # Hooks are already propagated to Codex by inject_hook_cli.py
+    # This is a no-op — kept for completeness and future editors with hooks
+    pass
+
+
+def propagate_mcp() -> None:
+    """Sync globally tracked MCP templates to global editor MCP configs."""
+    from install_steps.install_state import get_global_editors, get_mcp_templates
+
+    editors = get_global_editors()
+    templates = get_mcp_templates()
+    if not editors or not templates:
+        return
+
+    # MCP editor sync is handled by mcp_manager.py install --editor --scope global
+    import subprocess
+    scripts_dir = Path(__file__).resolve().parent
+
+    for editor in editors:
+        try:
+            subprocess.run(
+                ["python3", str(scripts_dir / "mcp_manager.py"),
+                 "install", "--editor", editor, "--scope", "global"] + templates,
+                capture_output=True, text=True, timeout=30,
+            )
+            print(f"  MCP synced to {editor} (global)")
+        except Exception as exc:
+            print(f"  Warning: MCP sync to {editor} failed: {exc}")
+
+
+def main() -> None:
+    args = set(sys.argv[1:])
+
+    if not args or "--rules" in args:
+        propagate_rules()
+    if "--hooks" in args:
+        propagate_hooks()
+    if "--mcp" in args:
+        propagate_mcp()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/rule_sources.py

@@ -23,8 +23,6 @@ from paths import RULES_DIR
 from url_fetch import fetch_url as fetch_url  # noqa: F811 — re-export
 
 _SOURCES_FILENAME = "sources.json"
-_FETCH_TIMEOUT = 30  # seconds
-_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10MB
 
 
 # ---------------------------------------------------------------------------
@@ -83,6 +81,9 @@ def save_sources(rules_dir: Path | None = None,
 
 def register_url_source(rules_dir: Path | None, rule_name: str, url: str) -> None:
     """Add or update a URL source entry."""
+    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] = {

package/scripts/update_projects.py

@@ -25,9 +25,15 @@ def _update_project(project: dict[str, Any], install_script: str, extra_args: li
     project_path = project["path"]
     start = time.monotonic()
 
+    # Pass saved editors from registry so update re-installs the same editors
+    cmd_args = ["python3", install_script, "--local"] + extra_args
+    project_editors = project.get("editors", [])
+    if project_editors:
+        cmd_args.extend(["--editors", ",".join(project_editors)])
+
     try:
         proc = subprocess.run(
-            ["python3", install_script, "--local"] + extra_args,
+            cmd_args,
             cwd=project_path,
             capture_output=True,
             text=True,

package/scripts/url_fetch.py

@@ -37,6 +37,11 @@ def fetch_url(url: str) -> bytes:
     ctx = ssl.create_default_context()
     with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
         data = resp.read(_FETCH_MAX_BYTES)
+        # Detect truncation — if there's more data, the response exceeds the limit
+        if resp.read(1):
+            raise ValueError(
+                f"Response exceeds {_FETCH_MAX_BYTES} byte limit: {url}"
+            )
 
     # Basic binary detection — reject if null bytes present
     if b"\x00" in data: