@jaguilar87/gaia 5.1.0-rc.3 → 5.1.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gaia",
       "description": "Security-first multi-agent orchestration for Claude Code. Specialized agents cover the full development lifecycle — analysis, planning, execution, deployment — with codebase-aware context injection. Every command is risk-classified: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
-      "version": "5.1.0-rc.3",
+      "version": "5.1.0",
       "category": "devops",
       "author": {
         "name": "jaguilar87",
@@ -18,7 +18,8 @@
       "homepage": "https://github.com/metraton/gaia#readme",
       "source": {
         "source": "github",
-        "repo": "metraton/gaia"
+        "repo": "metraton/gaia",
+        "ref": "v5.1.0"
       }
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia",
-  "version": "5.1.0-rc.3",
+  "version": "5.1.0",
   "description": "Security-first multi-agent orchestration for Claude Code. Agents span the full lifecycle; commands are risk-classified \u2014 reads run free, state changes need approval, irreversible ops blocked.",
   "author": {
     "name": "jaguilar87",
@@ -20,177 +20,5 @@
     "devops",
     "security",
     "orchestration"
-  ],
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
-          }
-        ]
-      },
-      {
-        "matcher": "Task",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
-          }
-        ]
-      },
-      {
-        "matcher": "Agent",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
-          }
-        ]
-      },
-      {
-        "matcher": "SendMessage",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Edit|Write|Glob|Grep|WebSearch|WebFetch|NotebookEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"
-          }
-        ]
-      },
-      {
-        "matcher": "AskUserQuestion",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"
-          }
-        ]
-      }
-    ],
-    "SubagentStop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/subagent_stop.py"
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "startup",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session_end_hook.py"
-          }
-        ]
-      }
-    ],
-    "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_compact.py"
-          }
-        ]
-      }
-    ],
-    "PostCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_compact.py"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/stop_hook.py"
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/task_completed.py"
-          }
-        ]
-      }
-    ],
-    "SubagentStart": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/subagent_start.py"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_submit.py"
-          }
-        ]
-      }
-    ],
-    "ElicitationResult": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/elicitation_result.py"
-          }
-        ]
-      }
-    ]
-  }
+  ]
 }

package/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.0] - 2026-07-03
+
+## [5.1.0-rc.4] - 2026-07-03
+
 ## [5.1.0-rc.3] - 2026-07-03
 
 ## [5.1.0-rc.2] - 2026-07-02

package/bin/plugin-dryrun.sh

@@ -31,7 +31,7 @@ if [[ "${1:-}" == "--functional" ]]; then
 fi
 
 # ---------------------------------------------------------------------------
-# (a) Pack -> prepack regenerates the root inline plugin.json + hooks/hooks.json
+# (a) Pack -> prepack regenerates the root plugin.json (metadata only) + hooks/hooks.json
 # ---------------------------------------------------------------------------
 cd "${REPO_ROOT}"
 echo "[dryrun] packing tarball (prepack regenerates root manifests)..."
@@ -118,15 +118,24 @@ else
   echo "  [PASS] no dist/ in tarball (package root is the plugin)"
 fi
 
-# The inline-hooks workaround MUST be present, and every referenced entry-point
-# file must exist under the plugin root.
-if python3 - "${ROOT}/.claude-plugin/plugin.json" "${ROOT}" <<'PY'
+# Hooks are declared ONLY in hooks/hooks.json. plugin.json must NOT embed an
+# inline 'hooks' block -- CC reads both, so an inline block double-registers
+# every hook. Assert its absence, and assert every entry point referenced by
+# hooks/hooks.json exists under the plugin root.
+if python3 - "${ROOT}/.claude-plugin/plugin.json" "${ROOT}/hooks/hooks.json" "${ROOT}" <<'PY'
 import json, os, re, sys
 
-plugin_json, root = sys.argv[1], sys.argv[2]
-data = json.load(open(plugin_json))
+plugin_json, hooks_json, root = sys.argv[1], sys.argv[2], sys.argv[3]
+
+plugin = json.load(open(plugin_json))
+assert "hooks" not in plugin, (
+    "plugin.json embeds an inline 'hooks' block -- hooks must live only in "
+    "hooks/hooks.json (an inline block double-registers every hook)"
+)
+
+data = json.load(open(hooks_json))
 hooks = data.get("hooks")
-assert isinstance(hooks, dict) and hooks, "plugin.json is missing a non-empty inline 'hooks' block"
+assert isinstance(hooks, dict) and hooks, "hooks/hooks.json is missing a non-empty 'hooks' block"
 
 missing = []
 for event, entries in hooks.items():
@@ -135,13 +144,13 @@ for event, entries in hooks.items():
             m = re.search(r"\$\{CLAUDE_PLUGIN_ROOT\}/(\S+\.py)", h.get("command", ""))
             if m and not os.path.isfile(os.path.join(root, m.group(1))):
                 missing.append(m.group(1))
-assert not missing, f"inline hook entry points not found under plugin root: {sorted(set(missing))}"
-print(f"  inline hooks: {len(hooks)} events, all entry points resolve")
+assert not missing, f"hook entry points not found under plugin root: {sorted(set(missing))}"
+print(f"  hooks.json: {len(hooks)} events, all entry points resolve; plugin.json has no inline hooks")
 PY
 then
-  echo "  [PASS] inline hooks block valid + entry points resolve"
+  echo "  [PASS] hooks declared once (hooks.json only) + entry points resolve"
 else
-  echo "  [FAIL] inline hooks block invalid or entry points missing"
+  echo "  [FAIL] hooks declaration invalid (inline block present or entry points missing)"
   fail=1
 fi
 

package/bin/pre-publish-validate.js

@@ -601,9 +601,24 @@ class PrePublishValidator {
           if (plugin.version !== expectedVersion) {
             versionMismatches.push(`marketplace/${plugin.name}: ${plugin.version}`);
           }
+          // For git/github object sources a `source.ref` pins `/plugin install`
+          // to a fixed release tag (`v<version>`). release:prepare's
+          // bumpMarketplace writes it atomically with the version. Tolerant
+          // when absent (refless resolves the repo's default HEAD -- a valid
+          // pre-pin state); strict when present so a stale/hand-edited ref that
+          // would serve the wrong tag is caught here rather than after publish.
+          const src = plugin.source;
+          if (src && typeof src === 'object' &&
+              (src.source === 'github' || src.source === 'git') &&
+              src.ref !== undefined) {
+            const expectedRef = `v${expectedVersion}`;
+            if (src.ref !== expectedRef) {
+              versionMismatches.push(`marketplace/${plugin.name}.source.ref: ${src.ref}`);
+            }
+          }
         }
         if (!versionMismatches.some(m => m.startsWith('marketplace/'))) {
-          this.log(`  ✓ marketplace.json plugin versions match`, 'success');
+          this.log(`  ✓ marketplace.json plugin versions${marketplaceData.plugins.some(p => p.source && p.source.ref) ? ' + source.ref pins' : ''} match`, 'success');
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.1.0-rc.3",
+  "version": "5.1.0",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gaia"
-version = "5.1.0-rc.3"
+version = "5.1.0"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.11"
 license = {text = "MIT"}

package/scripts/build-plugin.py

@@ -4,9 +4,14 @@ Build script for the gaia plugin.
 
 Under the `source: npm` delivery model the published package root IS the
 plugin -- there is no dist/ bundle. This script only regenerates the two
-generated manifests (.claude-plugin/plugin.json with inline hooks, and
+generated manifests (.claude-plugin/plugin.json and the canonical
 hooks/hooks.json) in place; it never cleans or copies component files.
 
+Hooks are declared in exactly ONE place: hooks/hooks.json (the standard
+plugin convention Claude Code reads). plugin.json does NOT embed an inline
+`hooks` block -- doing so made Claude Code register every hook twice (once
+from the inline block, once from hooks.json), so every event fired twice.
+
 Usage:
     python3 scripts/build-plugin.py <plugin-name> --manifests-only [--output-dir <path>]
 
@@ -233,10 +238,11 @@ def _get_entry_point(event_name: str, entries: list[str]) -> str:
 def generate_plugin_json(manifest: dict) -> dict:
     """Generate .claude-plugin/plugin.json from manifest.
 
-    Embeds hooks inline under the 'hooks' key so that CC can load them at
-    runtime from the plugin cache, bypassing the install-time path expansion
-    bug where ${CLAUDE_PLUGIN_ROOT} is resolved to $CWD/.claude/ instead of
-    the plugin cache directory.
+    Does NOT embed a `hooks` key. Hooks are declared solely in
+    hooks/hooks.json (the standard plugin convention Claude Code reads).
+    Embedding them inline here as well made CC read BOTH sources and register
+    every hook twice, so every event (SessionStart, SessionEnd, ...) fired
+    twice. Emitting hooks in exactly one place -- hooks.json -- fixes that.
     """
     version = manifest.get("version", "0.0.0")
     if version == "from:package.json":
@@ -248,12 +254,9 @@ def generate_plugin_json(manifest: dict) -> dict:
     plugin_name = manifest["plugin_name"]
     homepage = "https://github.com/metraton/gaia#readme"
 
-    # Build inline hooks structure from the same logic as generate_hooks_json().
-    # CC docs say plugin.json can declare hooks as a path, array, or inline object.
-    # Inline here avoids install-time path expansion via hooks/hooks.json.
-    hooks_data = generate_hooks_json(manifest)
-    inline_hooks = hooks_data["hooks"]
-
+    # NOTE: no `hooks` key here on purpose. Hooks live only in hooks/hooks.json
+    # (generated by generate_hooks_json / write_root_manifests). Declaring them
+    # here too caused CC to register each hook twice (double-firing).
     return {
         "name": plugin_name,
         "version": version,
@@ -268,7 +271,6 @@ def generate_plugin_json(manifest: dict) -> dict:
         "keywords": ["security", "devops"],
         "engines": {"claude-code": ">=2.1.0"},
         "categories": ["devops", "security", "orchestration"],
-        "hooks": inline_hooks,
     }
 
 
@@ -290,11 +292,11 @@ def write_root_manifests(plugin_name: str, output_dir: Path) -> None:
     """Regenerate ONLY the two plugin manifests into an existing directory.
 
     Writes:
-      - <output_dir>/.claude-plugin/plugin.json  (with the inline `hooks` block --
-        the ${CLAUDE_PLUGIN_ROOT} workaround so CC loads hooks from the plugin
-        cache under a `source: npm` install)
-      - <output_dir>/hooks/hooks.json            (canonical, manifest-derived;
-        the npm surface reads this via merge_local_hooks() in _install_helpers.py)
+      - <output_dir>/.claude-plugin/plugin.json  (metadata only -- NO inline
+        `hooks` block; declaring hooks here as well made CC register them twice)
+      - <output_dir>/hooks/hooks.json            (canonical, manifest-derived,
+        the SINGLE source of hook declarations; the npm surface reads this via
+        merge_local_hooks() in _install_helpers.py)
 
     Unlike build_plugin(), this NEVER cleans (`rmtree`) or copies component files.
     It is the pack-time / release-prepare mechanism that makes the repo root (and
@@ -345,8 +347,7 @@ def write_root_manifests(plugin_name: str, output_dir: Path) -> None:
     with open(plugin_json_path, "w") as f:
         json.dump(plugin_json, f, indent=2)
         f.write("\n")
-    inline_events = len(plugin_json.get("hooks", {}))
-    print(f"  Generated: .claude-plugin/plugin.json (inline hooks: {inline_events} events)", file=sys.stderr)
+    print("  Generated: .claude-plugin/plugin.json (metadata only, no inline hooks)", file=sys.stderr)
     print("Root manifests regenerated.", file=sys.stderr)
 
 

package/scripts/check_hooks_drift.py

@@ -2,10 +2,16 @@
 """Hooks-drift guard: fail if the committed generated hook artifacts diverge
 from what the manifest would produce.
 
-Background: ``hooks/hooks.json`` and the inline ``hooks`` object embedded in
-``.claude-plugin/plugin.json`` are GENERATED from ``build/gaia.manifest.json``
+Background: ``hooks/hooks.json`` is GENERATED from ``build/gaia.manifest.json``
 via ``generate_hooks_json`` (scripts/build-plugin.py), invoked by
-``npm run generate:plugin-root``. The manifest is the single source of truth.
+``npm run generate:plugin-root``. The manifest is the single source of truth,
+and hooks/hooks.json is the SINGLE place hooks are declared.
+
+``.claude-plugin/plugin.json`` must NOT embed an inline ``hooks`` block:
+Claude Code reads both the inline block and hooks/hooks.json, so declaring
+hooks in both registered every hook twice and made every event fire twice.
+This guard asserts hooks/hooks.json matches the manifest AND that plugin.json
+carries no ``hooks`` key.
 
 If a committed artifact no longer matches the manifest, someone either
 hand-edited a generated file or forgot to re-run the generator after editing
@@ -78,14 +84,14 @@ def main() -> int:
         )
         _report_diff("hooks/hooks.json", expected, hooks_json)
 
-    if plugin_hooks != expected:
+    if plugin_hooks:
         drift = True
         print(
-            "hooks-drift guard: .claude-plugin/plugin.json inline hooks != "
-            "generate_hooks_json(build/gaia.manifest.json)",
+            "hooks-drift guard: .claude-plugin/plugin.json embeds an inline "
+            "'hooks' block -- hooks must be declared ONLY in hooks/hooks.json. "
+            "An inline block makes Claude Code register every hook twice.",
             file=sys.stderr,
         )
-        _report_diff(".claude-plugin/plugin.json", expected, plugin_hooks)
 
     if drift:
         print(

package/scripts/release-prepare.mjs

@@ -94,9 +94,25 @@ function bumpMarketplace(rel, version) {
   const plugins = data.plugins || [];
   if (plugins.length === 0) throw new Error(`${rel}: no plugins[] to bump`);
   const befores = plugins.map((p) => `${p.name}=${p.version}`);
-  for (const plugin of plugins) plugin.version = version;
+  const tag = `v${version}`;
+  const refUpdates = [];
+  for (const plugin of plugins) {
+    plugin.version = version;
+    // Pin the source to the release tag for git/github sources so
+    // `/plugin install` serves a fixed, reproducible tag instead of tracking
+    // moving default-branch HEAD. Bumped atomically with the version so the
+    // ref can never go stale (the earlier flagged follow-up). Guard: only
+    // git/github object sources carry a ref -- npm/local sources must not.
+    const src = plugin.source;
+    if (src && typeof src === 'object' &&
+        (src.source === 'github' || src.source === 'git')) {
+      src.ref = tag;
+      refUpdates.push(`${plugin.name}.source.ref=${tag}`);
+    }
+  }
   writeText(rel, JSON.stringify(data, null, 2) + '\n');
-  return `${rel}: [${befores.join(', ')}] -> all ${version}`;
+  const refNote = refUpdates.length ? ` (${refUpdates.join(', ')})` : '';
+  return `${rel}: [${befores.join(', ')}] -> all ${version}${refNote}`;
 }
 
 function bumpPyproject(rel, version) {

package/skills/gaia-patterns/reference.md

@@ -129,7 +129,7 @@ The package ships a single `gaia` binary (`bin/gaia.js`) that dispatches to Pyth
 
 ## 2. Plugin Packaging
 
-Gaia ships as a **single, unified** plugin named `gaia`. There is **no `dist/` bundle** -- the npm package root (`@jaguilar87/gaia`) IS the plugin. The root `.claude-plugin/plugin.json` (hooks embedded inline) and `hooks/hooks.json` are generated from `build/gaia.manifest.json` at pack time (`prepack` -> `generate:plugin-root`) and tracked in git. One bundle carries all hooks, modules, agents, skills, tools, and config, and every install runs the full orchestrator surface.
+Gaia ships as a **single, unified** plugin named `gaia`. There is **no `dist/` bundle** -- the npm package root (`@jaguilar87/gaia`) IS the plugin. The root `.claude-plugin/plugin.json` (metadata only -- no inline hooks) and `hooks/hooks.json` (the canonical location Claude Code loads hooks from) are generated from `build/gaia.manifest.json` at pack time (`prepack` -> `generate:plugin-root`) and tracked in git. One bundle carries all hooks, modules, agents, skills, tools, and config, and every install runs the full orchestrator surface.
 
 ### Security Tiers (quick reference)
 
@@ -148,7 +148,7 @@ Enforcement: `blocked_commands.py` (permanent deny) + `mutative_verbs.py` (nonce
 
 ### Build
 
-There is **no `dist/` bundle** -- the package root IS the plugin. `scripts/build-plugin.py gaia --manifests-only --output-dir .` (run via `npm run generate:plugin-root`) reads `build/gaia.manifest.json`, resolves `"all"` fields to concrete file lists, and regenerates `.claude-plugin/plugin.json` (inline hooks) + `hooks/hooks.json` in place at the package root.
+There is **no `dist/` bundle** -- the package root IS the plugin. `scripts/build-plugin.py gaia --manifests-only --output-dir .` (run via `npm run generate:plugin-root`) reads `build/gaia.manifest.json`, resolves `"all"` fields to concrete file lists, and regenerates `.claude-plugin/plugin.json` (metadata only -- no inline hooks) + `hooks/hooks.json` (the canonical location Claude Code loads hooks from) in place at the package root.
 
 ### Publish
 

package/skills/gaia-release/SKILL.md

@@ -16,10 +16,10 @@ The norm for getting Gaia onto a machine and into the registry, organized as thr
 
 Gaia ships as a **single** plugin named `gaia` (`scripts/build-plugin.py` has `VALID_PLUGINS = ("gaia",)`). **The package root IS the plugin, and it is the same tree as the git repo root** -- there is no `dist/` bundle. That single tree reaches a workspace through **two distribution channels**, and a change can pass on one while breaking the other:
 
-- **plugin surface (git marketplace source)** -- Claude Code consumes the **git repository directly**: `.claude-plugin/marketplace.json` advertises the `gaia` plugin with `{"source": "github", "repo": "metraton/gaia"}`, so `/plugin marketplace add` + `/plugin install` make CC **clone the repo** into its plugin cache. **This is the channel that loads Gaia's agents, skills, and hooks in Claude Code.** The git source was adopted (commit `a43ef22`) precisely because the prior `source: npm` entry loaded **0 skills** on `/plugin install` -- a confirmed CC gap -- while the identical tree loads all 32 skills via a git/local source. CC reads the repo root's `.claude-plugin/plugin.json` with **hooks embedded inline** (the `${CLAUDE_PLUGIN_ROOT}` workaround) -- it does **not** use `settings.local.json` for hooks. The root `.claude-plugin/plugin.json` (inline hooks) and `hooks/hooks.json` are **generated from the manifest** (`prepack` / `generate:plugin-root`) and tracked in git, so the cloned tree already carries them. Git sources support version pinning by ref/sha; otherwise version resolution falls back to the marketplace entry's `version` field (still bumped atomically by `release:prepare`, which touches `plugin.version`, not `source`).
+- **plugin surface (git marketplace source)** -- Claude Code consumes the **git repository directly**: `.claude-plugin/marketplace.json` advertises the `gaia` plugin with `{"source": "github", "repo": "metraton/gaia"}`, so `/plugin marketplace add` + `/plugin install` make CC **clone the repo** into its plugin cache. **This is the channel that loads Gaia's agents, skills, and hooks in Claude Code.** The git source was adopted (commit `a43ef22`) precisely because the prior `source: npm` entry loaded **0 skills** on `/plugin install` -- a confirmed CC gap -- while the identical tree loads all 32 skills via a git/local source. CC loads hooks from the repo root's `hooks/hooks.json` (the standard plugin convention) -- it does **not** use `settings.local.json` for hooks, and the root `.claude-plugin/plugin.json` is **metadata only** (no inline `hooks` block). Hooks are declared in exactly ONE place because CC reads both a plugin.json inline block AND `hooks/hooks.json`; declaring them in both double-registered every hook and fired every event twice (fixed in `a1b1245`). Both `.claude-plugin/plugin.json` and `hooks/hooks.json` are **generated from the manifest** (`prepack` / `generate:plugin-root`) and tracked in git, so the cloned tree already carries them. Git sources support version pinning by ref/sha; otherwise version resolution falls back to the marketplace entry's `version` field (still bumped atomically by `release:prepare`, which touches `plugin.version`, not `source`).
 - **CLI / npm surface (npm package `@jaguilar87/gaia`)** -- `npm|pnpm install @jaguilar87/gaia` (and `gaia dev`) install the npm package; this is what provides the `gaia` **CLI** and the workspace wiring. `gaia install` then wires the workspace: it symlinks `.claude/{agents,tools,hooks,config,skills}` (plus a `CHANGELOG.md` link) to the installed package and merges hook events into `settings.local.json`. The DB is bootstrapped **lazily on first `gaia` CLI use** (`_ensure_db_bootstrapped` in `bin/gaia`) -- there is **no npm `postinstall`** (removed so the install is non-invasive and works identically under npm and pnpm, which ignores lifecycle scripts by default). This surface reads hooks from the package root's generated `hooks/hooks.json` (via `merge_local_hooks` in `_install_helpers.py`), which is regenerated at pack time from the manifest.
 
-The two channels ship from the **same source tree** (git repo root and npm package root are one and the same). That is why Layer 2 exists: the plugin surface can only be proven by materializing the plugin root -- packing the tarball, extracting it, and mounting the extracted root in a live Claude Code -- nothing else exercises the inline `plugin.json` / CC plugin loader.
+The two channels ship from the **same source tree** (git repo root and npm package root are one and the same). That is why Layer 2 exists: the plugin surface can only be proven by materializing the plugin root -- packing the tarball, extracting it, and mounting the extracted root in a live Claude Code -- nothing else exercises the root `plugin.json` / `hooks.json` / CC plugin loader.
 
 ## The three intentions
 
@@ -55,7 +55,7 @@ gaia release check              # add --functional for the opt-in live plugin pr
 
 1. `pre-publish:validate` -- the version-drift gate (`validate-manifests` in `ci.yml`, via `bin/pre-publish-validate.js --validate-only`). This is what catches a `package.json` / `pyproject.toml` / `plugin.json` / `marketplace.json` desync before it ships.
 2. `gaia:verify-install:local` -- packs (via the shared `_pack_helpers.pack_tarball`, the same primitive `gaia dev` uses) and installs into a throwaway sandbox (`bin/validate-sandbox.sh --target sandbox`). This proves the **npm surface** of exactly what a registry publish would ship. (This is `gaia-verify` mode `npm-sandbox`.)
-3. **Plugin-surface dry-run** (`bin/plugin-dryrun.sh`) -- packs the tarball itself, extracts it to a throwaway temp dir (the package root IS the plugin), and runs a **headless, offline** gate: filesystem asserts (root inline `plugin.json`, `hooks/hooks.json`, `bin/gaia`, `agents/`, `skills/`, and NO `dist/`) plus `claude plugin validate`. It touches no real workspace and spawns no session. `--functional` forwards to the script's own opt-in live `claude --plugin-dir <temp> -p '...'` probe (needs Claude auth/tokens -- never implicit). **SKIPs** (not fails) when the `claude` binary is not on PATH. This is the only place the plugin surface is proven before a tag exists. (This is `gaia-verify` mode `plugin`.) See the plugin-surface principle below for why a green npm sandbox does not cover it.
+3. **Plugin-surface dry-run** (`bin/plugin-dryrun.sh`) -- packs the tarball itself, extracts it to a throwaway temp dir (the package root IS the plugin), and runs a **headless, offline** gate: filesystem asserts (root `plugin.json` with NO inline `hooks` block, `hooks/hooks.json`, `bin/gaia`, `agents/`, `skills/`, and NO `dist/`) plus `claude plugin validate`. It touches no real workspace and spawns no session. `--functional` forwards to the script's own opt-in live `claude --plugin-dir <temp> -p '...'` probe (needs Claude auth/tokens -- never implicit). **SKIPs** (not fails) when the `claude` binary is not on PATH. This is the only place the plugin surface is proven before a tag exists. (This is `gaia-verify` mode `plugin`.) See the plugin-surface principle below for why a green npm sandbox does not cover it.
 4. `npm test` -- the L1 suite (the tests CI runs that reproduce locally).
 
 A `check` run that reports `FAIL` on gate 1 has failed a *subset* of CI, not passed a stand-in for it; a `FAIL`/`SKIP` on gate 3 means the plugin surface was never run (SKIP only when `claude` is genuinely absent) -- both gaps surface only after publish, when the fix costs another release. For the raw npm-script forms each gate wraps (useful when diagnosing which gate failed), see `reference.md` -> "Layer 2 runbook".
@@ -73,7 +73,7 @@ gaia release publish [version]              # add --dry-run to preview the seque
 | Step | Action | Notes |
 |------|--------|-------|
 | **(a)** | Determine the version | Default to the next **patch**. If the change is major/minor, **confirm with the user** (`NEEDS_INPUT`) before proceeding -- never silently pick major/minor. Pass the confirmed version as `gaia release publish`'s argument, or let it default to `patch`. |
-| **(b)** | `release:prepare <version>` -- `gaia release publish` step 1 | The atomic core: bumps the hand-owned version sources at once (`package.json`, `pyproject.toml`, `.claude-plugin/marketplace.json`, `CHANGELOG.md`), runs `generate:plugin-root` (regenerating the ROOT `.claude-plugin/plugin.json` inline-hooks + `hooks/hooks.json` from the manifest -- `plugin.json` version is inherited from `package.json`, not hand-bumped), then `pre-publish:validate`. Fails loud on any drift. No `dist/` bundle. This wraps `scripts/release-prepare.mjs` -- invoked by the flow, never run by hand. |
+| **(b)** | `release:prepare <version>` -- `gaia release publish` step 1 | The atomic core: bumps the hand-owned version sources at once (`package.json`, `pyproject.toml`, `.claude-plugin/marketplace.json`, `CHANGELOG.md`), runs `generate:plugin-root` (regenerating the ROOT `.claude-plugin/plugin.json` (metadata only) + `hooks/hooks.json` from the manifest -- `plugin.json` version is inherited from `package.json`, not hand-bumped), then `pre-publish:validate`. Fails loud on any drift. No `dist/` bundle. This wraps `scripts/release-prepare.mjs` -- invoked by the flow, never run by hand. |
 | **(c)** | Pre-flight that reproduces CI -- step 2 | `pre-publish:validate` already ran inside (b). Now `npm test` runs so the local gate matches CI before the tag exists. Layer 2 should already be green. |
 | **(d)** | Commit -- step 3 | `git add` (the version-source paths only) + `git commit` -- local-safe, not T3. Idempotent: nothing-to-commit on a tree already at the target version is a PASS, not a failure. |
 | **(e)** | Tag, **force-free** -- step 4 | A *new* annotated tag (`v<version>`); never moves an existing one. If the remote diverged, reconcile with **merge, not rebase** (rebase forces a tag move, hard-denied locally). See `reference.md` -> "Reconciling a diverged remote". |
@@ -103,7 +103,7 @@ A fresh install or an edit is invisible until Claude Code picks it up, and *how*
 ## Principles -- why the sequence is normed, not optional
 
 - **The pre-flight reproduces what CI validates, not a subset of it.** When the local check skips a gate CI runs (`pre-publish:validate`), that gate's failures surface only *after* publishing, on the published tarball, where the only remedy is another release. That is exactly how a `pyproject.toml` drift shipped green-local and red-CI. Layer 2 step 1 and Layer 3 step (c) close the gap. See `reference.md` -> "The pre-flight reproduces what CI validates".
-- **The plugin surface is only proven by packing the tarball and mounting the extracted root.** The npm sandbox exercises the symlink / `settings.local.json` path; it never touches the root inline `plugin.json` / `hooks.json` or CC's plugin loader. The tarball can be missing files, carry broken inline hooks, or fail to expose `bin/gaia` on PATH -- and none of that shows until CC mounts it. Layer 2 step 3 (`gaia:plugin-dryrun` -- pack, extract, headless validate) is the only pre-tag check that runs the plugin surface. Skipping it means the plugin breaks silently in production.
+- **The plugin surface is only proven by packing the tarball and mounting the extracted root.** The npm sandbox exercises the symlink / `settings.local.json` path; it never touches the root `plugin.json` / `hooks.json` or CC's plugin loader. The tarball can be missing files, carry a broken `hooks.json`, or fail to expose `bin/gaia` on PATH -- and none of that shows until CC mounts it. Layer 2 step 3 (`gaia:plugin-dryrun` -- pack, extract, headless validate) is the only pre-tag check that runs the plugin surface. Skipping it means the plugin breaks silently in production.
 - **Bump every version source in one step, never one at a time.** `pre-publish:validate` requires `package.json`, `pyproject.toml`, `.claude-plugin/plugin.json` (generated), `.claude-plugin/marketplace.json`, and the `CHANGELOG.md` top header to agree. `release:prepare` writes the hand-owned sources from one target version and regenerates `plugin.json` (version inherited from `package.json`), so a hand-desync is impossible. See `scripts/release-prepare.mjs`.
 - **Tag force-free; reconcile with merge, never rebase.** `publish.yml` no longer commits artifacts back to `main` (read-only checkout), so the remote does not auto-advance on release. But if the remote ever diverges, rebasing rewrites hashes and forces a tag move (`git tag -f` / `--force`), hard-denied by local hooks (`git_destructive` in `blocked_commands.py`, exit 2, not approvable). Merge preserves hashes and tags; a new release gets a *new* tag, never a moved one. See `reference.md` -> "Reconciling a diverged remote".
 - **A release ends at an installed, validated version -- not at the tag.** Pushing the tag only starts `publish.yml`. The intention is not satisfied until the workflow reaches its outcome, npm serves the new version, and it installs cleanly into the target (Layer 3 step (h)).
@@ -117,7 +117,7 @@ A fresh install or an edit is invisible until Claude Code picks it up, and *how*
 - **Bumping version sources one at a time** -- desyncs a source by hand; `pre-publish:validate` rejects the tree and a forgotten file ships if the check is skipped. Always go through `gaia release publish` (which invokes `release:prepare`), never a hand-edit.
 - **Rebase to reconcile a diverged remote** -- forces a tag move, hard-denied locally. Merge instead.
 - **Single-surface testing** -- a change can pass the npm sandbox and break the plugin mount, or vice versa. Layer 2 runs both surfaces for a reason.
-- **Stale root manifests** -- editing `build/gaia.manifest.json` or a hook entry without regenerating means the tarball ships old inline hooks. `prepack` regenerates at every `npm pack`, and `release:prepare` regenerates via `generate:plugin-root`; the dry-run packs fresh, so a stale manifest surfaces there.
+- **Stale root manifests** -- editing `build/gaia.manifest.json` or a hook entry without regenerating means the tarball ships a stale `hooks/hooks.json`. `prepack` regenerates at every `npm pack`, and `release:prepare` regenerates via `generate:plugin-root`; the dry-run packs fresh, so a stale manifest surfaces there.
 - **Blanket "restart Claude Code"** -- npm/pnpm hooks reload automatically; only the plugin surface needs `/reload-plugins`, and only a slash-command change needs a full restart. See "Reloading a change".
 - **Assuming a `postinstall` ran** -- there is none. The DB is bootstrapped lazily on first `gaia` CLI use; under pnpm a lifecycle hook would never fire anyway. If the DB is missing, run any `gaia` command (or `gaia install`), not "re-run postinstall".
 - **Local npm publish** -- bypasses the pipeline's pack + validate + sandbox gate.

package/skills/gaia-release/reference.md

@@ -37,7 +37,7 @@ gaia install --workspace <TARGET>
 cd /home/jorge/ws/me/gaia
 npm run gaia:install-local -- --workspace <TARGET>
 ```
-`gaia:install-local` runs `npm pack` (whose `prepack` regenerates the root inline `plugin.json` + `hooks/hooks.json`) + `validate-sandbox.sh --target local`. `gaia dev --mode pack` auto-detects npm vs pnpm from the target workspace, so it covers this case too; use the raw npm script only when diagnosing.
+`gaia:install-local` runs `npm pack` (whose `prepack` regenerates the root `plugin.json` (metadata only) + `hooks/hooks.json`) + `validate-sandbox.sh --target local`. `gaia dev --mode pack` auto-detects npm vs pnpm from the target workspace, so it covers this case too; use the raw npm script only when diagnosing.
 
 **fresh (wipe install metadata first):**
 Append `--fresh` to the `validate-sandbox.sh` form, or manually clear `node_modules/ package.json package-lock.json` (or the pnpm equivalents) in `<TARGET>` before reinstalling. Use when a prior install left state you want gone.
@@ -101,7 +101,7 @@ Sandbox path prints on exit; inspect `.claude/`, rerun checks, then `rm -rf` man
 ```
 npm run gaia:plugin-dryrun                   # pack -> temp extract -> headless validate -> trap cleanup
 ```
-`bin/plugin-dryrun.sh` packs the exact npm tarball (its `prepack` regenerates the root inline `plugin.json` + `hooks/hooks.json`), extracts it to a throwaway temp dir (the package root IS the plugin), and runs a headless, offline gate: filesystem asserts (root inline `plugin.json`, `hooks/hooks.json`, `bin/gaia`, `agents/`, `skills/`, and NO `dist/`) + `claude plugin validate`. It touches no real workspace and spawns no session; both temps are removed by an EXIT trap. `gaia release check` SKIPs (not fails) this gate when `claude` is not on PATH.
+`bin/plugin-dryrun.sh` packs the exact npm tarball (its `prepack` regenerates the root `plugin.json` (metadata only) + `hooks/hooks.json`), extracts it to a throwaway temp dir (the package root IS the plugin), and runs a headless, offline gate: filesystem asserts (root `plugin.json` present with NO inline `hooks` block, `hooks/hooks.json` with every entry point resolving, `bin/gaia`, `agents/`, `skills/`, and NO `dist/`) + `claude plugin validate`. It touches no real workspace and spawns no session; both temps are removed by an EXIT trap. `gaia release check` SKIPs (not fails) this gate when `claude` is not on PATH.
 
 For an optional live functional probe (needs Claude auth/tokens -- opt-in, never implicit):
 ```
@@ -139,7 +139,7 @@ gaia release publish --dry-run [version]    # preview the six-step sequence, exe
 1. Layer 2 (pre-release) must be green first -- run `gaia release check`.
 2. **`release:prepare <version>`** (`gaia release publish` step 1) -- the atomic bump. This wraps `scripts/release-prepare.mjs`, invoked by the flow, **never run by the user by hand**. In one command it:
    - writes `<version>` to the hand-owned sources at once -- `package.json`, `pyproject.toml`, `.claude-plugin/marketplace.json` (top-level `version`), and the `CHANGELOG.md` top header (inserts a dated stub above the current top if absent -- edit its body before release);
-   - runs `npm run generate:plugin-root` to regenerate the ROOT `.claude-plugin/plugin.json` (inline hooks) + `hooks/hooks.json` from the manifest -- `plugin.json`'s version is inherited from `package.json` (`from:package.json`), so it is NOT hand-bumped. No `dist/` bundle;
+   - runs `npm run generate:plugin-root` to regenerate the ROOT `.claude-plugin/plugin.json` (metadata only -- no inline hooks) + `hooks/hooks.json` from the manifest -- `plugin.json`'s version is inherited from `package.json` (`from:package.json`), so it is NOT hand-bumped. No `dist/` bundle;
    - runs `npm run pre-publish:validate` and fails loud on any drift.
 
    This replaces hand-bumping one file at a time. The two real escapes a hand-bump leaves are a `pyproject.toml` left behind on a prior version (caught only by `pre-publish:validate`) and a `marketplace.json` that still advertises the old top-level version. `release:prepare` makes the desync impossible because all hand-owned sources are written from one target version and `plugin.json` is generated from it. For a bare semver: `5.0.5` for stable, `5.1.0-rc.1` for RC (no leading `v` -- the tag adds it). Idempotent: re-running with the same version is a no-op bump that re-validates.
@@ -177,7 +177,7 @@ Symptoms encountered in real install sessions, with the root cause and the fix.
 | `.claude/` not wired after install | `gaia install` not run, or it exited non-zero | `cat ~/.gaia/last-install-error.json` (written by `gaia install` on failure). Re-run `gaia install --workspace <path>`. If it persists, file a bug. |
 | `gaia doctor` walks up to the user `.claude/` instead of the workspace | Workspace not initialized (`.claude/` missing or no `plugin-registry.json`) | Re-run `gaia install --workspace <path>`. |
 | DB missing / `no such table` on first use | Lazy bootstrap did not run (e.g. `gaia` never invoked yet) | Run any `gaia` command (it triggers `_ensure_db_bootstrapped`), or `gaia install` for the full seed. There is no postinstall to "re-run". |
-| Plugin mounts but hooks never fire | Generated inline `plugin.json` / `hooks.json` broken at the package root, or CC did not reload | Regenerate (`npm run generate:plugin-root`), re-run `npm run gaia:plugin-dryrun`, and `/reload-plugins`. Inspect the root `.claude-plugin/plugin.json` for the inline `hooks` block. |
+| Plugin mounts but hooks never fire | Generated `hooks/hooks.json` broken at the package root, or CC did not reload | Regenerate (`npm run generate:plugin-root`), re-run `npm run gaia:plugin-dryrun`, and `/reload-plugins`. Inspect the root `hooks/hooks.json` (the canonical hook source); `.claude-plugin/plugin.json` is metadata only and must NOT carry an inline `hooks` block. |
 | `bootstrap exited 1: table projects has no column named identity` | Schema/bootstrap drift (old seed SQL) | Update to a build whose seed matches the current schema. |
 | `Permission denied` invoking a hook `.py` | Exec bit lost on cross-platform checkout | Hooks are invoked via `python3 <script>` (see `build-plugin.py` `generate_hooks_json`), so the exec bit should not matter; if it does, update to a build that uses the `python3 <script>` invoker. |
 | Agent says "no conozco Gaia" or "developer agent does not exist" | `settings.local.json` missing or mis-wired (npm surface) | Re-run `gaia install`. In plugin surface, `/reload-plugins`. |
@@ -205,7 +205,7 @@ A green pre-flight only protects the release if it runs the same gates CI runs.
 **Pre-publish gate (Layer 2):**
 - `pytest tests/` green (or `npm test` for the L1 subset).
 - `npm run pre-publish:validate` green locally -- the version-drift gate (`validate-manifests` in `ci.yml`).
-- `npm pack --dry-run` confirms `scripts/bootstrap_database.sh`, `.claude-plugin/plugin.json` (with inline hooks), and `hooks/hooks.json` are included in the tarball, and that `dist/` is NOT.
+- `npm pack --dry-run` confirms `scripts/bootstrap_database.sh`, `.claude-plugin/plugin.json` (metadata only), and `hooks/hooks.json` (the canonical hook source) are included in the tarball, and that `dist/` is NOT.
 - `npm run gaia:verify-install:local` green (npm surface).
 - `npm run gaia:plugin-dryrun` green (plugin surface -- pack + extract + headless validate).
 
@@ -214,7 +214,7 @@ A green pre-flight only protects the release if it runs the same gates CI runs.
 The workflow at `.github/workflows/publish.yml` runs on every GitHub Release event (read-only checkout -- it neither commits nor pushes). It:
 - Checks out the exact tagged commit.
 - Installs deps with `npm ci`.
-- Packs the tarball with `npm pack` -- `prepack` (clean + `generate:plugin-root`) regenerates the root inline `plugin.json` + `hooks/hooks.json`, so the tarball root is a valid plugin root (the same tree the git plugin source serves). No `dist/` bundle is built or committed back.
+- Packs the tarball with `npm pack` -- `prepack` (clean + `generate:plugin-root`) regenerates the root `plugin.json` (metadata only) + `hooks/hooks.json`, so the tarball root is a valid plugin root (the same tree the git plugin source serves). No `dist/` bundle is built or committed back.
 - Runs `npm run pre-publish:validate` (after pack, so it sees the fresh root manifests).
 - Auto-detects npm tag from the version string: `*-rc.*` -> `rc`, `*-beta.*` -> `beta`, `*-alpha.*` -> `alpha`, else -> `latest`.
 - Runs the sandbox validation harness against the packed tarball (the gate).