@softspark/ai-toolkit 2.3.1 → 2.4.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ 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
+- **URL hook injection** — `ai-toolkit inject-hook https://...` fetches, caches, and injects hooks from HTTPS URLs. Cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on every `update`. `remove-hook` also unregisters URL source and cleans cache.
+- **Shared URL fetch module** — extracted `url_fetch.py` from `rule_sources.py` for reuse by both rule and hook URL sources.
+- **Hook URL source registry** — `hook_sources.py` tracks URL-sourced hooks in `sources.json` (analogous to `rule_sources.py`).
+- **Surgical Changes rule** — orphan cleanup protocol, match existing style, don't touch adjacent code (inspired by Karpathy's LLM coding guidelines).
+- **Goal-Driven Execution rule** — `step → verify: check` pattern for multi-step tasks, strong success criteria before looping.
+
+---
+
 ## v2.3.1 — Release Quality Gate (2026-04-14)
 
 ### Fixed

package/README.md

@@ -6,17 +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-606%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-618%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.3.1
+## What's New in v2.4.1
 
-- **URL rule registration** — `ai-toolkit add-rule https://...` with auto-refresh on every update
-- **Jira MCP template** — `ai-toolkit mcp add jira` with `postInstall` setup hints
-- **MCP template tracking** — globally installed templates saved in `state.json`, auto-synced on `update`
-- **Race condition fix** — parallel project updates no longer drop registry entries (fcntl.flock + atomic writes)
-- **Claude MCP paths fixed** — now uses `~/.claude.json` (global) and `.mcp.json` (project) per official docs
+- **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.
 
@@ -143,7 +143,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (606 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.3.1",
+  "version": "2.4.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -301,16 +301,16 @@ 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>`.
 
 Language rules are propagated to **all configured editors** — not just Claude. `dir_rules_shared.build_language_rules()` reads `app/rules/<lang>/*.md`, strips frontmatter, and returns combined content per language. Each directory-based generator (Cursor, Windsurf, Cline, Roo, Augment, Antigravity, Codex) emits `ai-toolkit-lang-<lang>` files in its native format. Registered custom rules (`~/.softspark/ai-toolkit/rules/`) are similarly propagated as `ai-toolkit-custom-<name>` files via `build_registered_rules()`.
 
-### Extension API (`inject-hook`)
-The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers.
+### Extension API (`inject-hook`, `inject-rule`)
+The `inject_section_cli.py` script provides a stable marker-based injection API. Any tool can add sections to `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content, using `<!-- TOOLKIT:START:<id> -->` / `<!-- TOOLKIT:END:<id> -->` markers. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`). Shared URL fetch logic lives in `url_fetch.py`.
 
 ### SLM Compilation (`compile-slm`)
 `scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).

package/app/rules/common/coding-style.md

@@ -7,11 +7,12 @@ version: "1.0.0"
 # Universal Coding Style
 
 ## Principles
-- KISS: simplest solution that works. Clever code is a liability.
+- KISS: simplest solution that works. Clever code is a liability. If 200 lines could be 50, rewrite.
 - DRY: extract when you repeat 3+ times, not before.
-- YAGNI: do not build features "just in case."
+- YAGNI: do not build features "just in case." No abstractions for single-use code.
 - Prefer immutability: use `const`, `final`, `val`, `let` by default.
 - Fail fast: validate inputs at boundaries, return early on errors.
+- State assumptions before coding. If uncertain or multiple interpretations exist, ask — don't pick silently.
 
 ## Naming
 - Use descriptive names that reveal intent (`remainingRetries`, not `r`).
@@ -45,6 +46,19 @@ version: "1.0.0"
 - Max line length: 80-120 characters depending on language convention.
 - Trailing commas in multi-line structures (where language supports).
 
+## Surgical Changes
+- Touch only what the task requires. Every changed line should trace to the request.
+- Match existing style, even if you would do it differently.
+- Do not "improve" adjacent code, comments, or formatting unprompted.
+- Orphan cleanup: remove imports/variables/functions that YOUR changes made unused.
+- Do not remove pre-existing dead code unless explicitly asked.
+
+## Goal-Driven Execution
+- Transform vague tasks into verifiable goals before starting.
+- For multi-step work, state a brief plan with verification per step:
+  `1. [Step] → verify: [check]`
+- Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.
+
 ## Anti-Patterns to Avoid
 - God classes/modules with 500+ lines and multiple responsibilities.
 - Deep nesting (>3 levels): use early returns and extract functions.

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');
 
@@ -65,8 +65,8 @@ const COMMANDS = {
   uninstall: 'Remove ai-toolkit from ~/.claude/',
   'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
-  'inject-hook': 'Inject external hooks into ~/.claude/settings.json (tagged with _source for idempotent updates)',
-  'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json',
+  'inject-hook': 'Inject external hooks (file or URL) into ~/.claude/settings.json (URL hooks auto-refresh on update)',
+  'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json (also unregisters URL source)',
   validate: 'Verify toolkit integrity',
   doctor: 'Check install health, hooks, and artifact drift',
   eject: 'Export standalone config (no symlinks, no toolkit dependency)',
@@ -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.
@@ -226,10 +243,11 @@ function showHelp() {
   console.log('  <rule-name>     Name of rule to unregister (filename without .md)');
   console.log('  [target-dir]    Target dir containing .claude/CLAUDE.md (default: $HOME)');
   console.log('\nOptions for inject-hook:');
-  console.log('  <hooks-file>    Path to JSON file with {"hooks": {"EventName": [...]}} format');
-  console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
+  console.log('  <hooks-file-or-url>  Path to JSON file or HTTPS URL with {"hooks": {"EventName": [...]}}');
+  console.log('  [hook-name]          Override source name (default: filename/URL stem)');
+  console.log('  [target-dir]         Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for remove-hook:');
-  console.log('  <source-name>   Source tag to remove (derived from hooks filename stem)');
+  console.log('  <source-name>   Source tag to remove (also unregisters URL source if present)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
   console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
@@ -330,6 +348,7 @@ function handleRemoveRule(args) {
   }
   const targetDir = args[1] || process.env.HOME;
   run(scriptPath('remove_rule.py'), [ruleName, targetDir]);
+  propagateGlobal('--rules');
 }
 
 /**
@@ -344,24 +363,32 @@ 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');
 }
 
 /**
- * Handle `ai-toolkit inject-hook` -- injects external hooks into settings.json.
+ * Handle `ai-toolkit inject-hook` -- injects external hooks (file or URL) into settings.json.
  * @param {string[]} args
  */
 function handleInjectHook(args) {
-  const hooksFile = args[0];
-  if (!hooksFile) {
-    console.error('Usage: ai-toolkit inject-hook <hooks-file.json> [target-dir]');
+  const source = args[0];
+  if (!source) {
+    console.error('Usage: ai-toolkit inject-hook <hooks-file-or-url> [hook-name] [target-dir]');
     process.exit(1);
   }
-  const absHooksFile = path.resolve(CWD, hooksFile);
-  const targetDir = args[1] || process.env.HOME;
-  run(scriptPath('inject_hook_cli.py'), [absHooksFile, targetDir]);
+  const isUrl = source.startsWith('https://') || source.startsWith('http://');
+  // For URLs pass as-is; for files resolve to absolute path
+  const resolvedSource = isUrl ? source : path.resolve(CWD, source);
+  // Pass remaining args through — Python CLI handles positional parsing
+  const remaining = args.slice(1);
+  run(scriptPath('inject_hook_cli.py'), [resolvedSource, ...remaining]);
 }
 
 /**
@@ -388,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,13 +335,13 @@ 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.
 
-### Extension API (`inject-hook`)
-`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content.
+### Extension API (`inject-hook`, `inject-rule`)
+`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`).
 
 ### Manifest Install (`--modules`, `--auto-detect`)
 `manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or enable auto-detection to select language rules based on files found in the project.

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."
 ---
 
@@ -34,10 +34,10 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `add-rule <rule.md> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
+| `add-rule <rule.md\|url> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
 | `remove-rule <name> [dir]` | Unregister rule and remove its block from `CLAUDE.md` |
-| `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
-| `remove-hook <name>` | Remove injected hooks by source name |
+| `inject-hook <file.json\|url> [name]` | Inject external hooks (file or URL) into settings.json (idempotent, `_source` tagged, URL hooks auto-refresh on update) |
+| `remove-hook <name>` | Remove injected hooks by source name (also unregisters URL source if present) |
 
 ## MCP Management
 

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

@@ -3,9 +3,9 @@ title: "Extension API Reference"
 category: reference
 service: ai-toolkit
 tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
-version: "1.3.9"
+version: "1.4.0"
 created: "2026-04-07"
-last_updated: "2026-04-12"
+last_updated: "2026-04-15"
 description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
 ---
 
@@ -23,9 +23,9 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 |---------|-------------|-----------|------------|
 | `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
-| `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag per entry | Yes |
-| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source` | Yes |
-| `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
+| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
@@ -60,13 +60,20 @@ The argument is the block name (file stem used during `inject-rule`). If the blo
 
 ## inject-hook
 
-Injects hook entries from a JSON file into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem.
+Injects hook entries from a JSON file or HTTPS URL into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem or URL last segment.
 
 ```bash
+# From local file
 npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json
+
+# From URL (HTTPS only) — cached locally, auto-refreshed on update
+npx @softspark/ai-toolkit inject-hook https://example.com/my-tool-hooks.json
+
+# With explicit source name
+npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hooks
 ```
 
-**Implementation:** `scripts/inject_hook_cli.py`.
+**Implementation:** `scripts/inject_hook_cli.py`, `scripts/hook_sources.py`, `scripts/url_fetch.py`.
 
 **Input format:**
 ```json
@@ -88,15 +95,19 @@ npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json
 }
 ```
 
-**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.
+**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. For URLs: `https://example.com/path/my-tool-hooks.json` → `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.
+
+**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/hooks/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced hooks are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
 
 **Idempotency:** Re-running strips all existing entries with the same source name, then appends the new ones. No duplicates accumulate.
 
-**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks.
+**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.
+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.
 
 ```bash
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
@@ -140,14 +151,14 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
 │  Public Extension API:                               │
 │    inject-rule  <file.md>     → CLAUDE.md            │
 │    remove-rule  <name>        → CLAUDE.md            │
-│    inject-hook  <file.json>   → settings.json        │
+│    inject-hook  <file|url>    → settings.json        │
 │    remove-hook  <name>        → settings.json        │
-│    add-rule     <file.md>     → rules/ registry      │
+│    add-rule     <file|url>    → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
 │    mcp install  <template>    → editor-native MCP    │
 │                                                      │
 │  Idempotent: markers (rules) / _source tags (hooks)  │
-│  ai-toolkit NEVER calls external services            │
+│  URL sources: cached + auto-refreshed on update      │
 └──────────────────────────────────────────────────────┘
                         ▲
                         │ uses API

package/llms-full.txt

@@ -4791,8 +4791,8 @@ Severity levels: HIGH (blocks deployment), WARN (should fix), INFO (best practic
 ### 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.
 
-### Extension API (`inject-hook`)
-`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content.
+### Extension API (`inject-hook`, `inject-rule`)
+`inject_section_cli.py` provides a stable marker-based API for injecting content into `CLAUDE.md`, `constitution.md`, or `ARCHITECTURE.md` without overwriting user content. `inject_hook_cli.py` injects hooks into `settings.json` with `_source` tags — supports both local files and HTTPS URLs (cached in `~/.softspark/ai-toolkit/hooks/external/`, auto-refreshed on `update`).
 
 ### Manifest Install (`--modules`, `--auto-detect`)
 `manifest.json` defines all installable components as named modules. Install individual modules with `ai-toolkit install --modules <name>` or enable auto-detection to select language rules based on files found in the project.
@@ -5167,10 +5167,10 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `add-rule <rule.md> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
+| `add-rule <rule.md\|url> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
 | `remove-rule <name> [dir]` | Unregister rule and remove its block from `CLAUDE.md` |
-| `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
-| `remove-hook <name>` | Remove injected hooks by source name |
+| `inject-hook <file.json\|url> [name]` | Inject external hooks (file or URL) into settings.json (idempotent, `_source` tagged, URL hooks auto-refresh on update) |
+| `remove-hook <name>` | Remove injected hooks by source name (also unregisters URL source if present) |
 
 ## MCP Management
 
@@ -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
@@ -6534,9 +6538,9 @@ title: "Extension API Reference"
 category: reference
 service: ai-toolkit
 tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
-version: "1.3.9"
+version: "1.4.0"
 created: "2026-04-07"
-last_updated: "2026-04-12"
+last_updated: "2026-04-15"
 description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
 ---
 
@@ -6554,9 +6558,9 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 |---------|-------------|-----------|------------|
 | `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
-| `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag per entry | Yes |
-| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source` | Yes |
-| `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
+| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
@@ -6591,13 +6595,20 @@ The argument is the block name (file stem used during `inject-rule`). If the blo
 
 ## inject-hook
 
-Injects hook entries from a JSON file into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem.
+Injects hook entries from a JSON file or HTTPS URL into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem or URL last segment.
 
 ```bash
+# From local file
 npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json
+
+# From URL (HTTPS only) — cached locally, auto-refreshed on update
+npx @softspark/ai-toolkit inject-hook https://example.com/my-tool-hooks.json
+
+# With explicit source name
+npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hooks
 ```
 
-**Implementation:** `scripts/inject_hook_cli.py`.
+**Implementation:** `scripts/inject_hook_cli.py`, `scripts/hook_sources.py`, `scripts/url_fetch.py`.
 
 **Input format:**
 ```json
@@ -6619,15 +6630,19 @@ npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json
 }
 ```
 
-**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.
+**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. For URLs: `https://example.com/path/my-tool-hooks.json` → `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.
+
+**URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/hooks/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced hooks are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
 
 **Idempotency:** Re-running strips all existing entries with the same source name, then appends the new ones. No duplicates accumulate.
 
-**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks.
+**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.
+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.
 
 ```bash
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
@@ -6671,14 +6686,14 @@ When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json`
 │  Public Extension API:                               │
 │    inject-rule  <file.md>     → CLAUDE.md            │
 │    remove-rule  <name>        → CLAUDE.md            │
-│    inject-hook  <file.json>   → settings.json        │
+│    inject-hook  <file|url>    → settings.json        │
 │    remove-hook  <name>        → settings.json        │
-│    add-rule     <file.md>     → rules/ registry      │
+│    add-rule     <file|url>    → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
 │    mcp install  <template>    → editor-native MCP    │
 │                                                      │
 │  Idempotent: markers (rules) / _source tags (hooks)  │
-│  ai-toolkit NEVER calls external services            │
+│  URL sources: cached + auto-refreshed on update      │
 └──────────────────────────────────────────────────────┘
                         ▲
                         │ uses API

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.3.1",
+  "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.3.1",
+  "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