@softspark/ai-toolkit 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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,16 @@
 [![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-613%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.3.1
+## What's New in v2.4.0
 
-- **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
+- **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
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -143,7 +142,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 (613 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.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -309,8 +309,8 @@ Lead Session (You)
 
 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

@@ -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)',
@@ -226,10 +226,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');
@@ -350,18 +351,21 @@ function handleAddRule(args) {
 }
 
 /**
- * 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]);
 }
 
 /**

package/kb/reference/architecture-overview.md

@@ -340,8 +340,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.

package/kb/reference/cli-reference.md

@@ -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/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,17 @@ 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.
 
 ## 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 +149,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
 
@@ -6534,9 +6534,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 +6554,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 +6591,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 +6626,17 @@ 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.
 
 ## 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 +6680,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.0",
   "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.0",
   "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/hook_sources.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""URL source registry for remotely-sourced hooks.
+
+Tracks which hooks were registered from a URL so that `ai-toolkit update`
+can re-fetch the latest version before injection.
+
+Metadata stored in ~/.softspark/ai-toolkit/hooks/external/sources.json.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import EXTERNAL_HOOKS_DIR
+
+_SOURCES_FILENAME = "sources.json"
+
+
+# ---------------------------------------------------------------------------
+# Load / Save
+# ---------------------------------------------------------------------------
+
+def _sources_path(hooks_dir: Path | None = None) -> Path:
+    return (hooks_dir or EXTERNAL_HOOKS_DIR) / _SOURCES_FILENAME
+
+
+def load_sources(hooks_dir: Path | None = None) -> dict[str, dict[str, Any]]:
+    """Load sources.json. Returns {} if missing or corrupt."""
+    path = _sources_path(hooks_dir)
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data.get("hooks", {})
+        return {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_sources(hooks_dir: Path | None = None,
+                 sources: dict[str, dict[str, Any]] | None = None) -> None:
+    """Write sources.json atomically."""
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    path = _sources_path(hooks_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps({"schema_version": 1, "hooks": sources or {}}, indent=2)
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".sources_", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def register_url_source(hooks_dir: Path | None, hook_name: str, url: str) -> None:
+    """Add or update a URL source entry."""
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    sources[hook_name] = {
+        "url": url,
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    save_sources(hooks_dir, sources)
+
+
+def unregister_source(hooks_dir: Path | None, hook_name: str) -> bool:
+    """Remove a source entry. Returns True if found and removed."""
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    if hook_name in sources:
+        del sources[hook_name]
+        save_sources(hooks_dir, sources)
+        return True
+    return False
+
+
+def get_url_hooks(hooks_dir: Path | None = None) -> dict[str, str]:
+    """Return {hook_name: url} for all URL-sourced hooks."""
+    sources = load_sources(hooks_dir)
+    return {name: entry["url"] for name, entry in sources.items() if "url" in entry}

package/scripts/inject_hook_cli.py

@@ -7,15 +7,20 @@ hooks alongside ai-toolkit's hooks.  Each injected file is tagged with a
 and removal is safe.
 
 Usage:
-    inject_hook_cli.py <hooks-file.json> [target-dir]
+    inject_hook_cli.py <hooks-file-or-url> [hook-name] [target-dir]
     inject_hook_cli.py --remove <hook-source-name> [target-dir]
 
 Arguments:
-    hooks-file    Path to a JSON file with ``{"hooks": {"EventName": [...]}}``
-    target-dir    Directory containing ``.claude/settings.json`` (default: $HOME)
+    hooks-file-or-url  Path to a JSON file or HTTPS URL with
+                       ``{"hooks": {"EventName": [...]}}``
+    hook-name          Override the source name (default: filename stem or
+                       URL last segment)
+    target-dir         Directory containing ``.claude/settings.json``
+                       (default: $HOME)
 
 Flags:
     --remove      Remove all hook entries tagged with the given source name
+                  (also unregisters URL source if present)
 
 The source name is derived from the filename stem (e.g.,
 ``rag-mcp-hooks.json`` becomes ``"rag-mcp-hooks"``).  All entries are tagged
@@ -34,9 +39,13 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import sys
+import urllib.parse
 from pathlib import Path
 
+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"
 
@@ -70,6 +79,23 @@ def save_json(path: str, data: dict) -> None:
         f.write("\n")
 
 
+# ---------------------------------------------------------------------------
+# URL helpers
+# ---------------------------------------------------------------------------
+
+def _is_url(source: str) -> bool:
+    """Check if source looks like an HTTP(S) URL."""
+    return source.startswith("https://") or source.startswith("http://")
+
+
+def _name_from_url(url: str) -> str:
+    """Derive a hook source name from a URL's last path segment."""
+    parsed = urllib.parse.urlparse(url)
+    filename = parsed.path.rstrip("/").split("/")[-1]
+    stem = filename.rsplit(".", 1)[0] if "." in filename else filename
+    return re.sub(r"[^a-zA-Z0-9_-]", "", stem)
+
+
 # ---------------------------------------------------------------------------
 # Core logic
 # ---------------------------------------------------------------------------
@@ -157,23 +183,93 @@ def merge_hooks(new_hooks: dict, existing_hooks: dict, source: str) -> dict:
 # CLI actions
 # ---------------------------------------------------------------------------
 
-def inject(hooks_file: str, target_dir: str) -> None:
-    """Inject hooks from *hooks_file* into the target settings.json.
+def _fetch_and_cache(url: str, source: str) -> str:
+    """Fetch hooks JSON from URL, cache locally, register source.
 
     Args:
-        hooks_file: Path to the external hooks JSON file.
-        target_dir: Directory containing ``.claude/settings.json``.
+        url: HTTPS URL to fetch.
+        source: Source name for caching and registry.
+
+    Returns:
+        Path to the cached hooks JSON file.
     """
-    # Derive source name from filename stem
-    source = Path(hooks_file).stem
-    if source == PROTECTED_SOURCE:
-        print(
-            f"Error: source name '{PROTECTED_SOURCE}' is reserved. "
-            "Rename your hooks file.",
-            file=sys.stderr,
-        )
+    from url_fetch import fetch_url
+    from hook_sources import register_url_source
+    from paths import EXTERNAL_HOOKS_DIR
+
+    EXTERNAL_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+
+    try:
+        data = fetch_url(url)
+    except Exception as exc:
+        print(f"Error fetching URL: {exc}", file=sys.stderr)
         sys.exit(1)
 
+    # Validate JSON before caching
+    try:
+        parsed = json.loads(data)
+    except json.JSONDecodeError as exc:
+        print(f"Error: URL returned invalid JSON: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    if "hooks" not in parsed:
+        print(f"Warning: no 'hooks' key found in URL response", file=sys.stderr)
+
+    cached_path = EXTERNAL_HOOKS_DIR / f"{source}.json"
+    cached_path.write_bytes(data)
+    register_url_source(None, source, url)
+
+    return str(cached_path)
+
+
+def inject(hooks_file: str, target_dir: str, source_override: str = "") -> None:
+    """Inject hooks from *hooks_file* (or URL) into the target settings.json.
+
+    Args:
+        hooks_file: Path to the external hooks JSON file, or an HTTPS URL.
+        target_dir: Directory containing ``.claude/settings.json``.
+        source_override: Explicit source name (overrides filename-derived name).
+    """
+    is_url = _is_url(hooks_file)
+
+    if is_url:
+        if hooks_file.startswith("http://"):
+            print(
+                "Error: only HTTPS URLs are supported. Use https:// for security.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        source = source_override or _name_from_url(hooks_file)
+        source = re.sub(r"[^a-zA-Z0-9_-]", "", source)
+        if not source:
+            print(
+                "Error: could not derive hook name from URL. "
+                "Provide one explicitly.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        hooks_file = _fetch_and_cache(hooks_file, source)
+        print(f"Fetched hooks from URL (source: '{source}')")
+    else:
+        # Derive source name from filename stem
+        source = source_override or Path(hooks_file).stem
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved. "
+                "Rename your hooks file.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
     # Load the hooks file
     try:
         hooks_data = load_json(hooks_file)
@@ -218,6 +314,8 @@ def inject(hooks_file: str, target_dir: str) -> None:
 def remove(source_name: str, target_dir: str) -> None:
     """Remove all hook entries tagged with *source_name*.
 
+    Also unregisters the URL source if it was URL-sourced.
+
     Args:
         source_name: The ``_source`` tag to remove.
         target_dir: Directory containing ``.claude/settings.json``.
@@ -256,6 +354,21 @@ 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}")
 
+    # Unregister URL source if present
+    try:
+        from hook_sources import unregister_source
+        from paths import EXTERNAL_HOOKS_DIR
+
+        if unregister_source(None, source_name):
+            print(f"Unregistered URL source '{source_name}'")
+
+        # Remove cached file if exists
+        cached = EXTERNAL_HOOKS_DIR / f"{source_name}.json"
+        if cached.is_file():
+            cached.unlink()
+    except ImportError:
+        pass
+
 
 # ---------------------------------------------------------------------------
 # Argument parsing
@@ -265,16 +378,19 @@ def _parse_args(argv: list[str]) -> dict:
     """Parse CLI arguments.
 
     Returns:
-        Dict with keys: remove_mode, remove_name, source_file, target_dir.
+        Dict with keys: remove_mode, remove_name, source_file, hook_name,
+        target_dir.
     """
     result: dict = {
         "remove_mode": False,
         "remove_name": "",
         "source_file": "",
+        "hook_name": "",
         "target_dir": str(Path.home()),
     }
 
     i = 0
+    positional = 0
     while i < len(argv):
         arg = argv[i]
         if arg == "--remove":
@@ -287,10 +403,25 @@ def _parse_args(argv: list[str]) -> dict:
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}", file=sys.stderr)
             sys.exit(1)
-        elif not result["source_file"] and not result["remove_mode"]:
-            result["source_file"] = arg
         else:
-            result["target_dir"] = arg
+            if positional == 0:
+                if not result["remove_mode"]:
+                    result["source_file"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 1:
+                if _is_url(result["source_file"]):
+                    # Second positional after URL could be hook-name or target-dir
+                    # If it looks like a path (starts with / or ~ or .), it's target-dir
+                    if arg.startswith(("/", "~", ".")):
+                        result["target_dir"] = arg
+                    else:
+                        result["hook_name"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 2:
+                result["target_dir"] = arg
+            positional += 1
         i += 1
 
     return result
@@ -309,7 +440,7 @@ def main() -> None:
     source_file = args["source_file"]
     if not source_file:
         print(
-            "Usage: inject_hook_cli.py <hooks-file.json> [target-dir]",
+            "Usage: inject_hook_cli.py <hooks-file-or-url> [hook-name] [target-dir]",
             file=sys.stderr,
         )
         print(
@@ -318,12 +449,13 @@ def main() -> None:
         )
         sys.exit(1)
 
-    source_path = Path(source_file)
-    if not source_path.is_file():
-        print(f"Hooks file not found: {source_path}", file=sys.stderr)
-        sys.exit(1)
+    if not _is_url(source_file):
+        source_path = Path(source_file)
+        if not source_path.is_file():
+            print(f"Hooks file not found: {source_path}", file=sys.stderr)
+            sys.exit(1)
 
-    inject(source_file, args["target_dir"])
+    inject(source_file, args["target_dir"], source_override=args["hook_name"])
 
 
 if __name__ == "__main__":

package/scripts/install.py

@@ -47,7 +47,7 @@ from emission import agent_count as count_agents, skill_count as count_skills
 # Step modules
 from install_steps.symlinks import install_agents, install_skills, clean_legacy_commands
 from install_steps.hooks import install_hooks
-from install_steps.markers import install_marker_files, inject_rules
+from install_steps.markers import install_marker_files, inject_rules, refresh_url_hooks
 from install_steps.ai_tools import install_ai_tools, install_local_project, run_script
 from install_steps.install_state import (
     load_state,
@@ -432,6 +432,9 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run,
                  refresh_urls=True)
 
+    if not dry_run:
+        refresh_url_hooks(str(target_dir))
+
     _sync_mcp_templates(dry_run)
 
 

package/scripts/install_steps/markers.py

@@ -99,6 +99,47 @@ def _refresh_url_rules(rules_dir: Path) -> None:
                 print(f"           No cached version — rule will be skipped.")
 
 
+def refresh_url_hooks(target_dir: str | None = None) -> None:
+    """Re-fetch all URL-sourced hooks and re-inject them.
+
+    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 paths import EXTERNAL_HOOKS_DIR
+    from url_fetch import fetch_url
+    import json
+
+    url_hooks = get_url_hooks()
+    if not url_hooks:
+        return
+
+    print("  Refreshing URL-sourced hooks...")
+    target = target_dir or str(Path.home())
+
+    for hook_name, url in url_hooks.items():
+        cached_file = EXTERNAL_HOOKS_DIR / f"{hook_name}.json"
+        try:
+            data = fetch_url(url)
+            # Validate JSON before caching
+            json.loads(data)
+            cached_file.write_bytes(data)
+            print(f"  Refreshed: {hook_name} (from {url})")
+        except Exception as exc:
+            if cached_file.is_file():
+                print(f"  Warning: could not refresh '{hook_name}' from {url}: {exc}")
+                print(f"           Using cached version.")
+            else:
+                print(f"  Warning: could not fetch '{hook_name}' from {url}: {exc}")
+                print(f"           No cached version — hook will be skipped.")
+                continue
+
+        # Re-inject from cached file
+        if cached_file.is_file():
+            from inject_hook_cli import inject
+            inject(str(cached_file), target, source_override=hook_name)
+
+
 def _inject_rules_dry_run(rules_dir: Path) -> None:
     rules_src = app_dir / "rules"
     rule_names = " ".join(

package/scripts/paths.py

@@ -25,6 +25,7 @@ LEGACY_DATA_DIR = Path.home() / ".ai-toolkit"
 
 # Sub-directories under TOOLKIT_DATA_DIR
 HOOKS_DIR = TOOLKIT_DATA_DIR / "hooks"
+EXTERNAL_HOOKS_DIR = HOOKS_DIR / "external"
 RULES_DIR = TOOLKIT_DATA_DIR / "rules"
 SESSIONS_DIR = TOOLKIT_DATA_DIR / "sessions"
 COMPACTIONS_DIR = TOOLKIT_DATA_DIR / "compactions"

package/scripts/rule_sources.py

@@ -12,17 +12,15 @@ from __future__ import annotations
 
 import json
 import os
-import ssl
 import sys
 import tempfile
-import urllib.request
-import urllib.error
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 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
@@ -112,27 +110,5 @@ def get_url_rules(rules_dir: Path | None = None) -> dict[str, str]:
 
 
 # ---------------------------------------------------------------------------
-# Fetch
+# Fetch — delegated to shared url_fetch module (re-exported above)
 # ---------------------------------------------------------------------------
-
-def fetch_url(url: str) -> bytes:
-    """Fetch URL content. HTTPS only, 30s timeout, 10MB cap.
-
-    Raises:
-        ValueError: if URL is not HTTPS
-        urllib.error.URLError: on network failure
-    """
-    if not url.startswith("https://"):
-        raise ValueError(
-            f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
-        )
-
-    ctx = ssl.create_default_context()
-    with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
-        data = resp.read(_FETCH_MAX_BYTES)
-
-    # Basic binary detection — reject if null bytes present
-    if b"\x00" in data:
-        raise ValueError(f"URL returned binary content, expected markdown: {url}")
-
-    return data

package/scripts/url_fetch.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Shared URL fetch utility for ai-toolkit.
+
+HTTPS-only, timeout-capped, size-limited fetcher used by both
+rule_sources and hook_sources.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import ssl
+import urllib.error
+import urllib.request
+
+_FETCH_TIMEOUT = 30  # seconds
+_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10MB
+
+
+def fetch_url(url: str) -> bytes:
+    """Fetch URL content. HTTPS only, 30s timeout, 10MB cap.
+
+    Args:
+        url: The HTTPS URL to fetch.
+
+    Returns:
+        Raw bytes of the response body.
+
+    Raises:
+        ValueError: if URL is not HTTPS or returns binary content.
+        urllib.error.URLError: on network failure.
+    """
+    if not url.startswith("https://"):
+        raise ValueError(
+            f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
+        )
+
+    ctx = ssl.create_default_context()
+    with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
+        data = resp.read(_FETCH_MAX_BYTES)
+
+    # Basic binary detection — reject if null bytes present
+    if b"\x00" in data:
+        raise ValueError(f"URL returned binary content: {url}")
+
+    return data