@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/hooks/modules/core/paths.py

@@ -125,29 +125,28 @@ def get_memory_dir(subdir: Optional[str] = None) -> Path:
     return memory_dir
 
 
-def get_session_dir() -> Path:
+def get_events_dir() -> Path:
     """
-    Get the active session directory, creating it if necessary.
+    Get the events directory, creating it if necessary.
 
     Returns:
-        Path to .claude/session/active/
+        Path to .claude/events/
     """
-    session_dir = get_plugin_data_dir() / "session" / "active"
-    session_dir.mkdir(parents=True, exist_ok=True)
-    return session_dir
+    events_dir = get_plugin_data_dir() / "events"
+    events_dir.mkdir(parents=True, exist_ok=True)
+    return events_dir
 
 
-def get_hooks_config_dir() -> Path:
+def get_session_dir() -> Path:
     """
-    Get the hooks config directory.
+    Get the active session directory, creating it if necessary.
 
     Returns:
-        Path to hooks/config/
+        Path to .claude/session/active/
     """
-    # Config lives alongside the hooks modules
-    hooks_dir = Path(__file__).parent.parent.parent
-    config_dir = hooks_dir / "config"
-    return config_dir
+    session_dir = get_plugin_data_dir() / "session" / "active"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir
 
 
 def clear_path_cache():

package/hooks/modules/core/plugin_mode.py

@@ -6,9 +6,11 @@ Ops mode: T3 operations block with nonce for orchestrator agent approval flow.
 
 Detection order:
 1. plugin-registry.json in plugin data directory
-2. GAIA_PLUGIN_MODE env var fallback
-3. Default: "security" (most restrictive)
+2. NPM package name detection (gaia-ops vs gaia-security)
+3. GAIA_PLUGIN_MODE env var fallback
+4. Default: "security" (most restrictive)
 """
+from __future__ import annotations
 
 import json
 import logging
@@ -21,6 +23,54 @@ logger = logging.getLogger(__name__)
 VALID_MODES = ("security", "ops")
 DEFAULT_MODE = "security"
 
+# Map NPM package names to plugin modes
+_NPM_PACKAGE_MODE = {
+    "gaia-ops": "ops",
+    "gaia-security": "security",
+}
+
+
+def _detect_mode_from_npm_package() -> str | None:
+    """Detect plugin mode from the NPM package name.
+
+    When installed via npm, this module lives at a path like:
+      .../node_modules/@jaguilar87/gaia-ops/hooks/modules/core/plugin_mode.py
+
+    The package directory name (gaia-ops or gaia-security) determines the mode.
+    Also checks .claude/ symlinks as a secondary signal for npm installs.
+
+    Returns the mode string or None if not detectable.
+    """
+    # Primary: check our own file path for node_modules package name
+    module_path = Path(__file__).resolve()
+    parts = module_path.parts
+    for i, part in enumerate(parts):
+        if part == "node_modules" and i + 2 < len(parts):
+            # Could be @scope/package-name or just package-name
+            pkg_name = parts[i + 1]
+            if pkg_name.startswith("@") and i + 2 < len(parts):
+                pkg_name = parts[i + 2]
+            mode = _NPM_PACKAGE_MODE.get(pkg_name)
+            if mode:
+                logger.debug("Detected mode '%s' from npm package path: %s", mode, pkg_name)
+                return mode
+
+    # Secondary: check if .claude/agents symlink points to a gaia package
+    try:
+        from .paths import find_claude_dir
+        claude_dir = find_claude_dir()
+        agents_link = claude_dir / "agents"
+        if agents_link.is_symlink():
+            target = str(agents_link.resolve())
+            for pkg_name, mode in _NPM_PACKAGE_MODE.items():
+                if pkg_name in target:
+                    logger.debug("Detected mode '%s' from .claude/agents symlink target", mode)
+                    return mode
+    except Exception:
+        pass
+
+    return None
+
 
 @lru_cache(maxsize=1)
 def get_plugin_mode() -> str:
@@ -42,12 +92,32 @@ def get_plugin_mode() -> str:
     except Exception as e:
         logger.debug("Registry check failed (non-fatal): %s", e)
 
-    # 2. Env var fallback
+    # 2. CLAUDE_PLUGIN_ROOT + plugin.json (--plugin-dir mode)
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if plugin_root:
+        try:
+            pjson = Path(plugin_root) / ".claude-plugin" / "plugin.json"
+            if pjson.exists():
+                pdata = json.loads(pjson.read_text())
+                pname = pdata.get("name", "")
+                mode = _NPM_PACKAGE_MODE.get(pname)
+                if mode:
+                    logger.debug("Detected mode '%s' from plugin.json name: %s", mode, pname)
+                    return mode
+        except Exception as e:
+            logger.debug("Plugin.json check failed (non-fatal): %s", e)
+
+    # 3. NPM package name detection
+    npm_mode = _detect_mode_from_npm_package()
+    if npm_mode:
+        return npm_mode
+
+    # 4. Env var fallback
     mode = os.environ.get("GAIA_PLUGIN_MODE", "").lower()
     if mode in VALID_MODES:
         return mode
 
-    # 3. Default: security (most restrictive)
+    # 5. Default: security (most restrictive)
     return DEFAULT_MODE
 
 

package/hooks/modules/core/plugin_setup.py

@@ -1,8 +1,9 @@
 """First-time plugin setup for SessionStart hook.
 
 Detects first run via marker file in CLAUDE_PLUGIN_DATA.
-On first run, creates .claude/settings.json in the project with base permissions.
+On first run, merges gaia permissions into .claude/settings.local.json.
 """
+from __future__ import annotations
 
 import json
 import logging
@@ -16,6 +17,192 @@ logger = logging.getLogger(__name__)
 
 MARKER_FILE = ".plugin-initialized"
 
+# ---------------------------------------------------------------------------
+# Deny list — shared across all modes.  Aligned with blocked_commands.py
+# (hook-level enforcement) for dual-barrier security.  These rules are
+# merged into settings.local.json so Claude Code's native permission system
+# blocks the commands BEFORE they even reach the hook layer.
+# ---------------------------------------------------------------------------
+_DENY_RULES = [
+    # AWS — networking / data infrastructure (irreversible)
+    "Bash(aws ec2 delete-vpc:*)",
+    "Bash(aws ec2 delete-subnet:*)",
+    "Bash(aws ec2 delete-internet-gateway:*)",
+    "Bash(aws ec2 delete-route-table:*)",
+    "Bash(aws ec2 delete-route:*)",
+    "Bash(aws ec2 terminate-instances:*)",
+    "Bash(aws rds delete-db-instance:*)",
+    "Bash(aws rds delete-db-cluster:*)",
+    "Bash(aws dynamodb delete-table:*)",
+    "Bash(aws s3 rb:*)",
+    "Bash(aws s3api delete-bucket:*)",
+    "Bash(aws elasticache delete-cache-cluster:*)",
+    "Bash(aws elasticache delete-replication-group:*)",
+    "Bash(aws eks delete-cluster:*)",
+    # AWS — KMS / Organizations / Route53
+    "Bash(aws kms schedule-key-deletion:*)",
+    "Bash(aws organizations delete-organization:*)",
+    "Bash(aws route53 delete-hosted-zone:*)",
+    # AWS — IAM (mutative but denied at settings level too)
+    "Bash(aws iam delete-user:*)",
+    "Bash(aws iam delete-role:*)",
+    "Bash(aws iam delete-access-key:*)",
+    "Bash(aws iam delete-group:*)",
+    "Bash(aws iam delete-instance-profile:*)",
+    "Bash(aws iam delete-policy:*)",
+    "Bash(aws iam delete-role-policy:*)",
+    "Bash(aws iam delete-user-policy:*)",
+    "Bash(aws iam delete-group-policy:*)",
+    "Bash(aws iam detach-user-policy:*)",
+    "Bash(aws iam detach-role-policy:*)",
+    "Bash(aws iam detach-group-policy:*)",
+    "Bash(aws iam remove-user-from-group:*)",
+    # AWS — other destructive
+    "Bash(aws backup delete:*::*)",
+    "Bash(aws cloudformation delete-stack:*)",
+    "Bash(aws dynamodb delete-item:*)",
+    "Bash(aws ec2 delete-key-pair:*)",
+    "Bash(aws ec2 delete-snapshot:*)",
+    "Bash(aws ec2 delete-volume:*)",
+    "Bash(aws ec2 delete-security-group:*)",
+    "Bash(aws ec2 delete-network-interface:*)",
+    "Bash(aws lambda delete-function:*)",
+    "Bash(aws rds delete-db-cluster-parameter-group:*)",
+    "Bash(aws rds delete-db-parameter-group:*)",
+    "Bash(aws s3api delete-objects:*)",
+    "Bash(aws sns delete-topic:*)",
+    "Bash(aws sqs delete-queue:*)",
+    "Bash(aws eks delete-nodegroup:*)",
+    "Bash(aws eks delete-addon:*)",
+    # Azure — resource group / networking / data (irreversible)
+    "Bash(az group delete:*)",
+    "Bash(az network vnet delete:*)",
+    "Bash(az network vnet subnet delete:*)",
+    "Bash(az network nsg delete:*)",
+    "Bash(az network public-ip delete:*)",
+    "Bash(az network application-gateway delete:*)",
+    "Bash(az network lb delete:*)",
+    "Bash(az network dns zone delete:*)",
+    "Bash(az network private-dns zone delete:*)",
+    "Bash(az vm delete:*)",
+    "Bash(az vmss delete:*)",
+    "Bash(az disk delete:*)",
+    "Bash(az snapshot delete:*)",
+    "Bash(az image delete:*)",
+    # Azure — databases / storage
+    "Bash(az sql server delete:*)",
+    "Bash(az sql db delete:*)",
+    "Bash(az cosmosdb delete:*)",
+    "Bash(az redis delete:*)",
+    "Bash(az storage account delete:*)",
+    "Bash(az storage container delete:*)",
+    "Bash(az storage blob delete-batch:*)",
+    # Azure — AKS / container
+    "Bash(az aks delete:*)",
+    "Bash(az aks nodepool delete:*)",
+    "Bash(az acr delete:*)",
+    # Azure — IAM / key vault / functions
+    "Bash(az role assignment delete:*)",
+    "Bash(az role definition delete:*)",
+    "Bash(az ad app delete:*)",
+    "Bash(az ad sp delete:*)",
+    "Bash(az keyvault delete:*)",
+    "Bash(az keyvault key delete:*)",
+    "Bash(az keyvault secret delete:*)",
+    "Bash(az functionapp delete:*)",
+    "Bash(az webapp delete:*)",
+    # Azure — messaging / monitoring
+    "Bash(az servicebus namespace delete:*)",
+    "Bash(az servicebus queue delete:*)",
+    "Bash(az servicebus topic delete:*)",
+    "Bash(az eventhubs namespace delete:*)",
+    "Bash(az eventhubs eventhub delete:*)",
+    "Bash(az monitor action-group delete:*)",
+    # GCP — project / cluster / database (irreversible)
+    "Bash(gcloud projects delete:*)",
+    "Bash(gcloud container clusters delete:*)",
+    "Bash(gcloud container node-pools delete:*)",
+    "Bash(gcloud sql instances delete:*)",
+    "Bash(gcloud sql databases delete:*)",
+    "Bash(gcloud services disable:*)",
+    "Bash(gsutil rb:*)",
+    "Bash(gsutil rm -r:*)",
+    # GCP — compute / IAM / storage
+    "Bash(gcloud compute firewall-rules delete:*)",
+    "Bash(gcloud compute instances delete:*)",
+    "Bash(gcloud compute networks delete:*)",
+    "Bash(gcloud compute disks delete:*)",
+    "Bash(gcloud compute images delete:*)",
+    "Bash(gcloud compute snapshots delete:*)",
+    "Bash(gcloud iam roles delete:*)",
+    "Bash(gcloud storage rm:*)",
+    # Kubernetes — critical cluster operations
+    "Bash(kubectl delete namespace:*)",
+    "Bash(kubectl delete node:*)",
+    "Bash(kubectl delete cluster:*)",
+    "Bash(kubectl delete pv:*)",
+    "Bash(kubectl delete persistentvolume:*)",
+    "Bash(kubectl delete pvc:*)",
+    "Bash(kubectl delete persistentvolumeclaim:*)",
+    "Bash(kubectl delete crd:*)",
+    "Bash(kubectl delete customresourcedefinition:*)",
+    "Bash(kubectl delete mutatingwebhookconfiguration:*)",
+    "Bash(kubectl delete validatingwebhookconfiguration:*)",
+    "Bash(kubectl delete clusterrole:*)",
+    "Bash(kubectl delete clusterrolebinding:*)",
+    "Bash(kubectl drain:*)",
+    # Flux
+    "Bash(flux delete:*)",
+    # Git — force push (history rewrite)
+    "Bash(git push --force:*)",
+    "Bash(git push -f:*)",
+    "Bash(git push origin --force:*)",
+    "Bash(git push origin -f:*)",
+    # Disk / filesystem destruction
+    "Bash(dd:*)",
+    "Bash(fdisk:*)",
+    "Bash(mkfs:*)",
+    "Bash(mkfs.ext4:*)",
+    "Bash(mkfs.ext3:*)",
+    "Bash(mkfs.fat:*)",
+    "Bash(mkfs.ntfs:*)",
+    # -------------------------------------------------------------------
+    # Generic wildcard rules — catch ALL present and future services.
+    # These complement the granular rules above; if a new cloud service
+    # is added, these patterns block its delete operations automatically.
+    # -------------------------------------------------------------------
+    # AWS — any "delete-*" subcommand across all services
+    "Bash(aws * delete-*:*)",
+    "Bash(aws * terminate-*:*)",
+    # Azure — any "delete" subcommand across all services
+    "Bash(az * delete:*)",
+    # GCP — any "delete" subcommand across all services
+    "Bash(gcloud * delete:*)",
+    "Bash(gsutil rb:*)",
+    "Bash(gsutil rm:*)",
+    "Bash(gcloud storage rm:*)",
+    # Kubernetes — all delete and drain operations
+    "Bash(kubectl delete:*)",
+    "Bash(kubectl drain:*)",
+    # Terraform / Terragrunt — destroy
+    "Bash(terraform destroy:*)",
+    "Bash(terragrunt destroy:*)",
+    "Bash(terragrunt run-all destroy:*)",
+    # Helm — uninstall
+    "Bash(helm uninstall:*)",
+    "Bash(helm delete:*)",
+    # Flux — uninstall
+    "Bash(flux uninstall:*)",
+    # Docker — bulk prune
+    "Bash(docker system prune:*)",
+    "Bash(docker volume prune:*)",
+    # Git — destructive history operations
+    "Bash(git reset --hard:*)",
+    # Repo deletion
+    "Bash(gh repo delete:*)",
+    "Bash(glab project delete:*)",
+]
+
 # Base permissions for security-only mode
 SECURITY_PERMISSIONS = {
     "permissions": {
@@ -34,7 +221,7 @@ SECURITY_PERMISSIONS = {
             "WebSearch",
             "NotebookEdit",
         ],
-        "deny": [],
+        "deny": _DENY_RULES,
         "ask": [],
     }
 }
@@ -63,7 +250,7 @@ OPS_PERMISSIONS = {
             "Edit(/tmp/*)",
             "Write(/tmp/*)",
         ],
-        "deny": [],
+        "deny": _DENY_RULES,
         "ask": [],
     }
 }
@@ -128,18 +315,25 @@ def setup_project_permissions() -> bool:
     existing["permissions"]["deny"] = merged_deny
     existing["permissions"].setdefault("ask", [])
 
+    # Add env vars (smart merge: add if not present, don't overwrite)
+    env = existing.setdefault("env", {})
+    if "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" not in env:
+        env["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"] = "1"
+
     claude_dir.mkdir(parents=True, exist_ok=True)
     settings_path.write_text(json.dumps(existing, indent=2) + "\n")
-    logger.info("Merged gaia %s permissions into %s", mode, settings_path)
+    logger.info("Merged gaia %s permissions and env into %s", mode, settings_path)
     return True
 
 
 def ensure_plugin_registry() -> None:
-    """Create plugin-registry.json from CLAUDE_PLUGIN_ROOT if missing.
+    """Create plugin-registry.json if missing.
 
-    In plugin mode, CLAUDE_PLUGIN_ROOT looks like:
-      .../cache/marketplace/gaia-ops/4.4.0-rc.2
-    We extract the plugin name and version from the path.
+    Detection strategies (in order):
+    1. CLAUDE_PLUGIN_ROOT env var (plugin marketplace mode):
+       Path looks like .../cache/marketplace/gaia-ops/4.4.0-rc.2
+    2. NPM package detection: resolve package name and version from
+       node_modules path and package.json
     """
     import os
     data_dir = get_plugin_data_dir()
@@ -147,37 +341,215 @@ def ensure_plugin_registry() -> None:
     if registry_path.exists():
         return
 
-    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
-    if not plugin_root:
-        return
+    plugin_name = None
+    plugin_version = None
+    source = None
 
-    parts = Path(plugin_root).parts
-    if len(parts) < 2:
+    # Strategy 1: CLAUDE_PLUGIN_ROOT (plugin marketplace or --plugin-dir)
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if plugin_root:
+        root_path = Path(plugin_root)
+        # First, try to read .claude-plugin/plugin.json (most reliable)
+        plugin_json = root_path / ".claude-plugin" / "plugin.json"
+        if plugin_json.exists():
+            try:
+                pdata = json.loads(plugin_json.read_text())
+                plugin_name = pdata.get("name")
+                plugin_version = pdata.get("version")
+                source = "plugin-mode"
+            except (json.JSONDecodeError, OSError):
+                pass
+        # Fallback: parse path (marketplace layout: .../name/version)
+        if not plugin_name:
+            parts = root_path.parts
+            if len(parts) >= 2:
+                plugin_name = parts[-2]
+                plugin_version = parts[-1]
+                source = "plugin-mode"
+
+    # Strategy 2: NPM package detection
+    if not plugin_name:
+        npm_info = _detect_npm_package_info()
+        if npm_info:
+            plugin_name, plugin_version = npm_info
+            source = "npm-mode"
+
+    if not plugin_name:
         return
 
-    plugin_name = parts[-2]  # e.g. "gaia-ops" or "gaia-security"
-    plugin_version = parts[-1]  # e.g. "4.4.0-rc.2"
-
     registry = {
-        "installed": [{"name": plugin_name, "version": plugin_version}],
-        "source": "plugin-mode",
+        "installed": [{"name": plugin_name, "version": plugin_version or "unknown"}],
+        "source": source,
     }
+    data_dir.mkdir(parents=True, exist_ok=True)
     registry_path.write_text(json.dumps(registry, indent=2) + "\n")
-    logger.info("Created plugin-registry.json: %s@%s", plugin_name, plugin_version)
+    logger.info("Created plugin-registry.json: %s@%s (source: %s)", plugin_name, plugin_version, source)
+
+
+def _detect_npm_package_info() -> tuple[str, str | None] | None:
+    """Detect plugin name and version from NPM package path.
+
+    When installed via npm, this module lives at:
+      .../node_modules/@jaguilar87/gaia-ops/hooks/modules/core/plugin_setup.py
+
+    Returns (plugin_name, version) or None.
+    """
+    module_path = Path(__file__).resolve()
+    parts = module_path.parts
+
+    # Find node_modules in path and extract package name
+    pkg_name = None
+    pkg_root = None
+    for i, part in enumerate(parts):
+        if part == "node_modules" and i + 1 < len(parts):
+            next_part = parts[i + 1]
+            if next_part.startswith("@") and i + 2 < len(parts):
+                # Scoped package: @scope/name
+                pkg_name = parts[i + 2]
+                pkg_root = Path(*parts[:i + 3])
+            else:
+                pkg_name = next_part
+                pkg_root = Path(*parts[:i + 2])
+            break
+
+    if not pkg_name or pkg_name not in ("gaia-ops", "gaia-security"):
+        return None
+
+    # Try to read version from package.json
+    version = None
+    if pkg_root:
+        pkg_json = Path("/") / pkg_root / "package.json"
+        try:
+            if pkg_json.exists():
+                data = json.loads(pkg_json.read_text())
+                version = data.get("version")
+        except Exception:
+            pass
+
+    return (pkg_name, version)
+
+
+def setup_project_hooks() -> bool:
+    """Merge hooks from hooks.json into .claude/settings.local.json.
+
+    In npm mode, Claude Code reads hooks from settings files, not hooks.json.
+    This converts ${CLAUDE_PLUGIN_ROOT}/hooks/<script> paths to .claude/hooks/<script>
+    and merges them into settings.local.json with deduplication by command string.
+
+    Returns True if settings were modified.
+    """
+    import re
+
+    claude_dir = Path.cwd() / ".claude"
+    settings_path = claude_dir / "settings.local.json"
+
+    # Find hooks.json — try package root (npm) or plugin root
+    hooks_json_path = None
+    # Strategy 1: relative to this module (npm layout)
+    module_dir = Path(__file__).resolve().parent.parent.parent
+    candidate = module_dir / "hooks.json"
+    if candidate.is_file():
+        hooks_json_path = candidate
+    else:
+        # Strategy 2: .claude/hooks/hooks.json (symlinked)
+        candidate2 = claude_dir / "hooks" / "hooks.json"
+        if candidate2.is_file():
+            hooks_json_path = candidate2
+
+    if not hooks_json_path:
+        logger.info("hooks.json not found, skipping hooks merge")
+        return False
+
+    try:
+        hooks_data = json.loads(hooks_json_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        logger.warning("hooks.json is invalid, skipping hooks merge")
+        return False
+
+    # Unwrap outer "hooks" key if present
+    source_hooks = hooks_data.get("hooks", hooks_data)
+
+    # Convert ${CLAUDE_PLUGIN_ROOT}/hooks/<script> to .claude/hooks/<script>
+    def convert_command(cmd: str) -> str:
+        return re.sub(r'\$\{CLAUDE_PLUGIN_ROOT\}/hooks/', '.claude/hooks/', cmd)
+
+    converted_hooks: dict = {}
+    for event, entries in source_hooks.items():
+        converted_hooks[event] = []
+        for entry in entries:
+            new_entry = dict(entry)
+            if "hooks" in new_entry:
+                new_entry["hooks"] = [
+                    {**h, "command": convert_command(h["command"])} if "command" in h else h
+                    for h in new_entry["hooks"]
+                ]
+            converted_hooks[event].append(new_entry)
+
+    # Load existing settings.local.json
+    existing: dict = {}
+    if settings_path.exists():
+        try:
+            existing = json.loads(settings_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    # Smart merge: deduplicate by command string
+    existing_hooks = existing.get("hooks", {})
+    changed = False
+
+    for event, new_entries in converted_hooks.items():
+        if event not in existing_hooks:
+            existing_hooks[event] = new_entries
+            changed = True
+            continue
+
+        # Collect existing command strings
+        existing_commands: set = set()
+        for entry in existing_hooks[event]:
+            for h in entry.get("hooks", []):
+                if "command" in h:
+                    existing_commands.add(h["command"])
+
+        # Add entries whose commands are not already present
+        for new_entry in new_entries:
+            new_commands = [h["command"] for h in new_entry.get("hooks", []) if "command" in h]
+            all_present = len(new_commands) > 0 and all(c in existing_commands for c in new_commands)
+            if not all_present:
+                existing_hooks[event].append(new_entry)
+                changed = True
+
+    if not changed:
+        logger.info("settings.local.json hooks already up to date")
+        return False
+
+    existing["hooks"] = existing_hooks
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(existing, indent=2) + "\n")
+    logger.info("Merged hooks into %s", settings_path)
+    return True
 
 
-def run_first_time_setup() -> str | None:
-    """Run setup. Returns a reload message if permissions were written."""
-    # Always ensure registry and permissions exist (even on subsequent runs)
+def run_first_time_setup(mark_done: bool = True) -> str | None:
+    """Run setup. Returns a reload message if permissions were written.
+
+    Args:
+        mark_done: If True, mark the plugin as initialized after setup.
+                   Set to False when the caller wants to defer marking
+                   (e.g., UserPromptSubmit marks after showing the welcome).
+    """
+    # Always ensure registry, permissions, and hooks exist (even on subsequent runs)
     ensure_plugin_registry()
     reload_needed = setup_project_permissions()
+    hooks_changed = setup_project_hooks()
+    reload_needed = reload_needed or hooks_changed
 
     if not is_first_run():
         if reload_needed:
             return "Permissions updated. Run /reload-plugins to activate."
         return None
 
-    mark_initialized()
+    if mark_done:
+        mark_initialized()
 
     if reload_needed:
         mode = get_plugin_mode()

package/hooks/modules/events/__init__.py

@@ -0,0 +1 @@
+"""Event context system for cross-session operational event logging."""