nexo-brain 7.2.0 → 7.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.2.0` is the current packaged-runtime line. It is a minor release that consolidates three parallel workstreams into a single Guardian-active-by-default train. Block K roadmap closure: G1 enforcer active (PostToolUse nudge when the latest `nexo_task_open` returned `mode ∈ {defer, ask, verify}` and the operator has not executed the paired `next_action`), G3 SSH remote-write detector (catches `ssh host "cat > ..."`, `scp upload`, `rsync upload`, `sftp -b batch` and 10+ other patterns the local destructive gate never saw), new `src/guardian_runtime_config.py` resolver (env > `~/.nexo/personal/config/guardian-runtime-overrides.json` > default), and `_persist_guardian_hard_defaults` during `nexo update` so every non-ephemeral install gets Guardian in `hard` without manual env vars. F0.6 hardening wave: `nexo rollback f06` CLI with two-stage safe swap, `src/scripts/prune_runtime_backups.py` promoted from personal to core, the authoritative `docs/f06-layout-contract.md`, three new doctor boot-tier checks (`check_core_dev_packaged_install`, `check_dashboard_desktop_contract`, `check_f06_migration_consistency`), `scripts/nexo-migrate-nora.sh` + `scripts/f0-safe-apply-remote.sh` idempotent migration workflow, and v6.x→F0.6 rollback hardening tests. Adaptive weights: flips from "14-day calendar wait" to "14 days OR (≥200 samples AND ≥2 days)" + `_maybe_promote_adaptive_weights_empirically` auto-promotes shadow→learned during `nexo update` so mature installs feel the Cortex calibration immediately. Small-fixes batch: R34 `bool("unknown")==True` fix, `classify_scripts_dir` dedup by realpath, B10 module-level path constants lazy-evaluated in `public_contribution.py` / `tools_sessions.py` / `plugins/recover.py` / `plugins/update.py`, schedule override audit log at `runtime/logs/core-schedule-overrides.log`, `scripts/pre-release-verify.sh` + `docs/release-discipline.md`, and a pre-commit hook that blocks commits when `tool-enforcement-map.json` drifts from `src/plugins/`.
+Version `7.4.0` is the current packaged-runtime line. Hotfix minor release correcting three critical bugs that surfaced right after v7.2.0. B11 Guardian wire: new `src/hooks/pre_tool_use.py` entrypoint is now registered in `src/hooks/manifest.json` and `hooks/hooks.json` so the Claude Code PreToolUse event actually reaches Guardian — before this, `guardian-runtime-overrides.json` in hard mode was silently inert for G3-destructive, G3-SSH, and G4-guard_check gates. A parallel SSH prescreen in `hook_guardrails.process_pre_tool_event` forces `op=write` on remote-write patterns the local shell classifier could not see. B10 post-sync: `_run_post_install_hooks_fresh(dest, env)` invokes each whitelisted hook (`_persist_guardian_hard_defaults`, `_maybe_promote_adaptive_weights_empirically`) in a clean subprocess against the newly copied tree, so the first `nexo update` that introduces a new post-install hook actually runs it — previously the hook dispatch used the pre-upgrade module held in memory and silently no-op'd. B12 map distribution: `tool-enforcement-map.json` is now part of the npm `files` whitelist so fresh `npm install -g nexo-brain` ships it, closing the three-way gap (Brain npm + Desktop bundle + runtime sync) that prevented Desktop from ever discovering the map on new installs. Also ships the PE1 rapid items promised for this milestone: 5 additional `destructive_command` entries in `src/presets/entities_universal.json` (`curl_pipe_shell`, `dd_to_device`, `chmod_recursive_wide_open`, `ssh_remote_overwrite`, `scp_rsync_upload`; coverage floor raised from 7 to 12) and the `guardian-metrics` daily cron at 02:15 that feeds Fase C gate and the Guardian Proposals panel.
+
+Previously in `7.2.0`: minor release consolidating three parallel workstreams into a single Guardian-active-by-default train. Block K roadmap closure (G1 enforcer active, G3 SSH remote-write detector, `src/guardian_runtime_config.py` resolver, `_persist_guardian_hard_defaults` during `nexo update`). F0.6 hardening wave (`nexo rollback f06` CLI, `src/scripts/prune_runtime_backups.py` promoted to core, `docs/f06-layout-contract.md`, three new doctor boot-tier checks, `scripts/nexo-migrate-nora.sh` + `scripts/f0-safe-apply-remote.sh` idempotent migration). Adaptive weights flipped from "14-day calendar wait" to "14 days OR (≥200 samples AND ≥2 days)" with auto-promotion during `nexo update`. Small-fixes batch: R34 `bool("unknown")==True` fix, `classify_scripts_dir` dedup, B10 module-level path constants lazy-evaluated, schedule override audit log, `scripts/pre-release-verify.sh` + `docs/release-discipline.md`, pre-commit hook that blocks commits when `tool-enforcement-map.json` drifts from `src/plugins/`.
 
 Previously in `7.1.10`: follow-up over v7.1.8 that shipped two rescue batches of WIP stashed aside during the v7.1.8 release window. First rescue: `src/autonomy_mandate.py` expanded the mandate-detection vocabulary (hazlo todo / no pares / estás al mando / te dejo al mando / sigue sin parar / haz el plan completo), added three honest flags on `MandateState` (`execute_until_blocker`, `suppress_mid_task_menus`, `revalidate_after_compaction`) with session filtering, wired post/pre-compact hooks that read those flags, surfaced them through protocol/workflow handlers and session payload, and introduced the new `src/checkpoint_policy.py` module with tests. Second rescue: `scripts/verify_release_readiness.py` gained a smoke-artifact contract pass that validates `release-contracts/smoke/v<version>.json` before any tag push, the release-final audit skill references the new contract, `src/hook_guardrails.py` + `src/hooks/post_tool_use.py` refine the post-tool protocol reminder path with a new contract test, and a couple of core prompts (task-close evidence, r14 correction learning) got wording polish.
 

package/hooks/hooks.json

@@ -40,6 +40,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/pre_tool_use.py\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",
@@ -89,6 +89,7 @@
     ".claude-plugin/",
     ".mcp.json",
     "hooks/hooks.json",
+    "tool-enforcement-map.json",
     "README.md",
     "LICENSE"
   ]

package/src/auto_update.py

@@ -4648,25 +4648,27 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     except Exception as exc:
         actions.append(f"classifier-install-warning:{exc.__class__.__name__}")
 
+    # v7.3.0 fix for the post-v7.2.0 bug: ``_run_runtime_post_sync`` was
+    # invoking post-install hooks directly against the ``auto_update``
+    # module already loaded in this process (the OLD code). Any function
+    # added to auto_update in the CURRENT release therefore never ran on
+    # the first ``nexo update`` that introduced it — only on the next
+    # one. Exhibit A: v7.2.0 shipped ``_persist_guardian_hard_defaults``
+    # and ``_maybe_promote_adaptive_weights_empirically`` but
+    # ``guardian-runtime-overrides.json`` was not written on the operator's
+    # first upgrade until the functions were invoked manually.
+    #
+    # The fix runs those post-install hooks inside a clean Python
+    # subprocess that imports from the freshly-copied tree at
+    # ``dest/core`` (packaged) or ``dest`` (dev/legacy layout). The
+    # subprocess emits a single JSON line so the parent process can
+    # record each hook's outcome in ``actions``.
     try:
-        _emit_progress(progress_fn, "Persisting Guardian enforcement defaults...")
-        persisted, persist_message = _persist_guardian_hard_defaults(dest)
-        if persisted:
-            actions.append("guardian-hard-persisted")
-        if persist_message:
-            actions.append(persist_message)
+        _emit_progress(progress_fn, "Running post-install hooks from fresh code...")
+        fresh_actions = _run_post_install_hooks_fresh(dest, env=env)
+        actions.extend(fresh_actions)
     except Exception as exc:
-        actions.append(f"guardian-hard-persist-warning:{exc.__class__.__name__}")
-
-    try:
-        _emit_progress(progress_fn, "Promoting adaptive weights if enough data...")
-        promoted, promote_message = _maybe_promote_adaptive_weights_empirically(dest)
-        if promoted:
-            actions.append("adaptive-weights-promoted")
-        if promote_message:
-            actions.append(promote_message)
-    except Exception as exc:
-        actions.append(f"adaptive-weights-promote-warning:{exc.__class__.__name__}")
+        actions.append(f"post-install-hooks-fresh-warning:{exc.__class__.__name__}")
 
     _emit_progress(progress_fn, "Verifying runtime imports...")
     verify = subprocess.run(
@@ -4886,6 +4888,115 @@ def _maybe_promote_adaptive_weights_empirically(dest: Path) -> tuple[bool, str |
     return True, None
 
 
+# Whitelist of post-install hooks to invoke from the fresh tree. Each entry
+# is the function name inside ``auto_update.py`` of the freshly-copied
+# code. The subprocess resolves them on the NEW module and calls
+# ``fn(dest)`` returning ``(bool, str | None)``. New hooks added in
+# future releases only need an entry here — no extra wiring.
+_POST_INSTALL_FRESH_HOOKS = (
+    ("guardian-hard-persisted", "_persist_guardian_hard_defaults"),
+    ("adaptive-weights-promoted", "_maybe_promote_adaptive_weights_empirically"),
+)
+
+
+def _run_post_install_hooks_fresh(dest: Path, *, env: dict | None = None) -> list[str]:
+    """Execute post-install hooks from the freshly-copied code, not the old
+    module already loaded in this process.
+
+    Without this, any function added to ``auto_update.py`` in the current
+    release never runs on the first ``nexo update`` — only on the next
+    one. See the post-v7.2.0 bug: ``_persist_guardian_hard_defaults`` and
+    ``_maybe_promote_adaptive_weights_empirically`` both shipped in
+    v7.2.0 but neither fired until the operator ran the functions
+    manually.
+
+    Resolution order for the fresh code root:
+        1. ``<dest>/core`` (packaged/F0.6 layout).
+        2. ``<dest>`` (legacy/dev layout).
+
+    Subprocess contract: emits a single JSON line on stdout with per-hook
+    ``{"action": ..., "ok": bool, "changed": bool, "message": str|null}``.
+    Returns a list of action strings mirroring the shape the old in-process
+    path used, so callers that read ``actions`` keep working unchanged.
+    """
+    code_root = dest / "core"
+    if not code_root.is_dir():
+        code_root = dest
+    hook_specs = list(_POST_INSTALL_FRESH_HOOKS)
+    hook_specs_json = json.dumps(hook_specs)
+    dest_str = str(dest)
+    script = (
+        "import json, sys\n"
+        "from pathlib import Path\n"
+        f"sys.path.insert(0, {repr(str(code_root))})\n"
+        "hooks = json.loads(" + repr(hook_specs_json) + ")\n"
+        f"dest = Path({repr(dest_str)})\n"
+        "results = []\n"
+        "try:\n"
+        "    import auto_update as fresh\n"
+        "except Exception as exc:\n"
+        "    print(json.dumps({'error': 'import_auto_update_failed', 'detail': repr(exc)}))\n"
+        "    sys.exit(0)\n"
+        "for tag, fn_name in hooks:\n"
+        "    fn = getattr(fresh, fn_name, None)\n"
+        "    if fn is None:\n"
+        "        results.append({'action': tag, 'ok': False, 'changed': False, 'message': 'fn_missing:' + fn_name})\n"
+        "        continue\n"
+        "    try:\n"
+        "        changed, message = fn(dest)\n"
+        "        results.append({'action': tag, 'ok': True, 'changed': bool(changed), 'message': message})\n"
+        "    except Exception as exc:\n"
+        "        results.append({'action': tag, 'ok': False, 'changed': False, 'message': 'error:' + exc.__class__.__name__})\n"
+        "print(json.dumps({'hooks': results}))\n"
+    )
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-c", script],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            env=env or os.environ.copy(),
+        )
+    except subprocess.TimeoutExpired:
+        return ["post-install-hooks-fresh-warning:timeout"]
+    except Exception as exc:
+        return [f"post-install-hooks-fresh-warning:{exc.__class__.__name__}"]
+
+    if proc.returncode != 0:
+        return [f"post-install-hooks-fresh-warning:exit-{proc.returncode}"]
+
+    stdout = (proc.stdout or "").strip()
+    payload = None
+    for line in reversed(stdout.splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            payload = json.loads(line)
+            break
+        except Exception:
+            continue
+    if not isinstance(payload, dict):
+        return ["post-install-hooks-fresh-warning:no-json-line"]
+    if "error" in payload:
+        return [f"post-install-hooks-fresh-warning:{payload['error']}"]
+
+    actions: list[str] = []
+    hooks_out = payload.get("hooks")
+    if not isinstance(hooks_out, list):
+        return ["post-install-hooks-fresh-warning:bad-shape"]
+    for entry in hooks_out:
+        if not isinstance(entry, dict):
+            continue
+        tag = str(entry.get("action") or "")
+        if entry.get("ok") and entry.get("changed"):
+            actions.append(tag)
+        message = entry.get("message")
+        if message:
+            actions.append(str(message))
+    return actions
+
+
 def _parse_runtime_init_payload(stdout: str) -> dict:
     """Extract the JSON payload emitted by the runtime init helper."""
     lines = [line.strip() for line in stdout.splitlines() if line.strip()]

package/src/cli.py

@@ -3076,6 +3076,22 @@ def main():
     dashboard_parser.add_argument("action", choices=["on", "off", "status"], help="Start, stop, or check dashboard")
 
     # -- desktop bridge (read-only, for NEXO Desktop and any external UI) --
+    # v7.4.0 — lifecycle event bridge (guardian-claude-desktop-plan).
+    lifecycle_parser = sub.add_parser("lifecycle", help="Conversation lifecycle event handler (v7.4 Desktop bridge)")
+    lifecycle_sub = lifecycle_parser.add_subparsers(dest="lifecycle_command")
+
+    lrec_p = lifecycle_sub.add_parser("record", help="Record a lifecycle event")
+    lrec_p.add_argument("--event-id", required=True, help="UUID minted by the client (idempotency key)")
+    lrec_p.add_argument("--action", required=True, help="close|delete|archive|switch|app-exit|window-close")
+    lrec_p.add_argument("--conversation-id", required=True)
+    lrec_p.add_argument("--session-id", default="")
+    lrec_p.add_argument("--reason", default="user_action")
+    lrec_p.add_argument("--payload", default="", help="JSON-encoded payload_snapshot")
+    lrec_p.add_argument("--source", default="desktop")
+
+    lstat_p = lifecycle_sub.add_parser("status", help="Read the current delivery_status of an event")
+    lstat_p.add_argument("--event-id", required=True)
+
     # Fase E.5 — quarantine ops surfaced via Desktop Guardian Proposals panel.
     quarantine_parser = sub.add_parser("quarantine", help="Quarantine proposals (Fase E.5 Desktop UI)")
     quarantine_sub = quarantine_parser.add_subparsers(dest="quarantine_command")
@@ -3288,6 +3304,43 @@ def main():
         # No subcommand — show help.
         quarantine_parser.print_help()
         return 1
+    elif args.command == "lifecycle":
+        # v7.4.0 — bridge for NEXO Desktop's ConversationLifecycleService.
+        # Both subcommands emit a single JSON line to stdout so the
+        # caller (main.js runNexoCommand) can parse the ack directly.
+        import json as _json
+        import plugins.lifecycle_events as _lifecycle_plugin
+        if args.lifecycle_command == "record":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_event(
+                event_id=args.event_id,
+                action=args.action,
+                conversation_id=args.conversation_id,
+                session_id=args.session_id or "",
+                reason=args.reason or "user_action",
+                payload_snapshot=args.payload or "",
+                source=args.source or "desktop",
+                schema_version=1,
+            )
+            print(out)
+            try:
+                parsed = _json.loads(out)
+                status = str(parsed.get("status", ""))
+            except Exception:
+                status = ""
+            # Exit code 0 for terminal ok states, 2 for retryable_error so
+            # Desktop can distinguish "persisted + processed" from "try
+            # again on boot reconciliation". Rejected is exit 3 (bad input).
+            if status in ("processed", "already_processed", "accepted"):
+                return 0
+            if status == "retryable_error":
+                return 2
+            return 3
+        if args.lifecycle_command == "status":
+            out = _lifecycle_plugin.handle_nexo_lifecycle_status(args.event_id)
+            print(out)
+            return 0
+        lifecycle_parser.print_help()
+        return 1
     elif args.command in ("schema", "identity", "onboard", "scan-profile"):
         from desktop_bridge import cmd_schema, cmd_identity, cmd_onboard, cmd_scan_profile
         return {

package/src/client_sync.py

@@ -87,6 +87,9 @@ HOOK_TIMEOUTS_BY_EVENT = {
     "PreCompact": 15,
     "PostCompact": 15,
     "UserPromptSubmit": 5,
+    # PreToolUse is synchronous on every tool call — keep low. 8s gives room
+    # for DB lookups under load without stalling routine Edit/Write/Bash.
+    "PreToolUse": 8,
     "PostToolUse": 20,
     "Notification": 3,
     "SubagentStop": 10,

package/src/crons/manifest.json

@@ -192,6 +192,18 @@
       "run_on_boot": true,
       "run_on_wake": true
     },
+    {
+      "id": "guardian-metrics",
+      "script": "scripts/guardian_metrics_aggregate.py",
+      "schedule": {"hour": 2, "minute": 15},
+      "description": "Plan Consolidado 0.25 — daily aggregation of Guardian KPIs (capture rate, core rule violations, declared-done without evidence, false-positive correction, minutes between guard_check failures) from guardian-telemetry.ndjson to guardian-metrics.ndjson. Feeds Fase C gate + Guardian Proposals panel.",
+      "core": true,
+      "recovery_policy": "catchup",
+      "idempotent": true,
+      "max_catchup_age": 172800,
+      "run_on_boot": false,
+      "run_on_wake": false
+    },
     {
       "id": "auto-close-sessions",
       "script": "auto_close_sessions.py",

package/src/db/_schema.py

@@ -1311,6 +1311,46 @@ def _m44_entities_extended_schema(conn):
     _migrate_add_column(conn, "entities", "access_mode", "TEXT DEFAULT 'unknown'")
 
 
+def _m51_lifecycle_events(conn):
+    """v7.4.0 — durable lifecycle event store for the Desktop pipeline.
+
+    Matches the Desktop-side NDJSON queue contract:
+    event_id (PRIMARY KEY, uuid from Desktop), source (desktop|cron|...),
+    action (close|delete|archive|switch|app-exit|window-close),
+    conversation_id, session_id (claude session), reason,
+    payload_snapshot (JSON), delivery_status
+    (pending|accepted|processed|already_processed|rejected|retryable_error),
+    retry_count, created_at, processed_at, last_error.
+
+    Idempotency key is event_id. Re-delivery of the same event_id returns
+    status=already_processed without re-running any canonical side effect
+    (diary, stop, archive bookkeeping). This is the backbone of
+    guardian-claude-desktop-plan.md → "5. Idempotencia real".
+    """
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS lifecycle_events (
+            event_id TEXT PRIMARY KEY,
+            schema_version INTEGER NOT NULL DEFAULT 1,
+            source TEXT NOT NULL DEFAULT 'desktop',
+            action TEXT NOT NULL,
+            conversation_id TEXT NOT NULL,
+            session_id TEXT DEFAULT NULL,
+            reason TEXT DEFAULT 'user_action',
+            payload_snapshot TEXT DEFAULT '{}',
+            delivery_status TEXT NOT NULL DEFAULT 'accepted',
+            retry_count INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT DEFAULT (datetime('now')),
+            processed_at TEXT DEFAULT NULL,
+            last_error TEXT DEFAULT NULL
+        )
+        """
+    )
+    _migrate_add_index(conn, "idx_lifecycle_events_status", "lifecycle_events", "delivery_status")
+    _migrate_add_index(conn, "idx_lifecycle_events_conv", "lifecycle_events", "conversation_id")
+    _migrate_add_index(conn, "idx_lifecycle_events_action", "lifecycle_events", "action")
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -1362,6 +1402,7 @@ MIGRATIONS = [
     (48, "email_agent_contract_backfill", _m48_email_agent_contract_backfill),
     (49, "protocol_guard_ack_backfill", _m49_protocol_guard_ack_backfill),
     (50, "dedupe_nexo_product_learning_pair", _m50_dedupe_nexo_product_learning_pair),
+    (51, "lifecycle_events", _m51_lifecycle_events),
 ]
 
 

package/src/hook_guardrails.py

@@ -1000,6 +1000,27 @@ def process_pre_tool_event(payload: dict) -> dict:
             _shell_cmd = _extract_bash_command(tool_input)
             if _classify_destructive_intent(_shell_cmd):
                 op = "delete"  # force the main gate to keep evaluating
+    # Block K G3 SSH prescreen: SSH remote-write patterns never map to
+    # ``write``/``delete`` via ``_classify_bash_operation`` (they look like
+    # ``other`` at shell level because the mutation happens on the remote
+    # end). Without this prescreen the ``if op not in {'write', 'delete'}``
+    # early-return below lets them sail past the main G3-SSH gate — the
+    # exact failure mode uncovered on v7.2.0: ``ssh host "cat > file"``
+    # in hard mode never emitted the deny response.
+    if tool_name == "Bash" and op not in {"write", "delete"}:
+        try:
+            from guardian_runtime_config import resolve_guardian_flag as _resolve_ssh
+            _g3_ssh_mode_prescreen = _resolve_ssh(
+                "G3_SSH_ENFORCE_REMOTE_WRITE", default="shadow"
+            )
+        except Exception:
+            _g3_ssh_mode_prescreen = os.environ.get(
+                "NEXO_G3_SSH_ENFORCE_REMOTE_WRITE", "shadow"
+            ).strip().lower()
+        if _g3_ssh_mode_prescreen in {"shadow", "hard"}:
+            _shell_cmd_ssh = _extract_bash_command(tool_input)
+            if _classify_ssh_remote_write(_shell_cmd_ssh):
+                op = "write"  # force the main gate to keep evaluating
     if op not in {"write", "delete"}:
         return {"ok": True, "skipped": True, "reason": "operation not blocked", "strictness": get_protocol_strictness()}
 

package/src/hooks/manifest.json

@@ -3,6 +3,7 @@
   "hooks": [
     { "event": "SessionStart",     "handler": "src/hooks/session_start.py",   "critical": true  },
     { "event": "UserPromptSubmit", "handler": "src/hooks/auto_capture.py",    "critical": false },
+    { "event": "PreToolUse",       "handler": "src/hooks/pre_tool_use.py",    "critical": true  },
     { "event": "PostToolUse",      "handler": "src/hooks/post_tool_use.py",   "critical": false },
     { "event": "PreCompact",       "handler": "src/hooks/pre_compact.py",     "critical": true  },
     { "event": "Stop",             "handler": "src/hooks/stop.py",            "critical": true  },

package/src/hooks/pre_tool_use.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""PreToolUse unified handler.
+
+v7.3.0 wires the Block K Guardian gates (G3 destructive + G3 SSH + G4
+guard_check + conditioned-file blocks + automation live-repo guard)
+into Claude Code's PreToolUse event. Without this handler, the
+``process_pre_tool_event`` logic in ``hook_guardrails.py`` was code
+that never ran in production — the post-v7.2.0 bug Francisco found
+on 2026-04-22.
+
+Responsibility:
+    - Read the hook payload from stdin.
+    - Resolve the NEXO sid from the payload / env.
+    - Delegate to ``hook_guardrails.process_pre_tool_event``.
+    - If the result carries ``status == "blocked"`` AND at least one
+      block has severity error (hard mode), emit a PreToolUse denial
+      response so Claude Code refuses to execute the tool.
+    - Otherwise exit cleanly.
+
+The hook NEVER crashes the tool pipeline: any exception drops to a
+safe no-op return and the tool is allowed (fail-open for robustness;
+a hard denial requires a successful evaluation that saw a hard block).
+Observability hooks still record the run via ``hook_observability``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+_DIR = Path(__file__).resolve().parent
+if str(_DIR.parent) not in sys.path:
+    sys.path.insert(0, str(_DIR.parent))
+
+
+def _read_stdin_json() -> dict:
+    if sys.stdin.isatty():
+        return {}
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return {}
+        return json.loads(raw)
+    except Exception:
+        return {}
+
+
+def _record(duration_ms: int, exit_code: int, summary: str) -> None:
+    try:
+        sys.path.insert(0, str(_DIR.parent))
+        import hook_observability  # type: ignore
+        hook_observability.record_hook_run(
+            "pre_tool_use",
+            duration_ms=duration_ms,
+            exit_code=exit_code,
+            summary=summary,
+            session_id=os.environ.get("CLAUDE_SESSION_ID", ""),
+        )
+    except Exception:
+        pass
+
+
+def _format_block_reason(result: dict) -> str:
+    """Build a human-readable reason for the deny response."""
+    blocks = result.get("blocks") or []
+    if not isinstance(blocks, list) or not blocks:
+        return "Guardian: tool execution blocked by a hard-mode gate."
+    first = blocks[0] if isinstance(blocks[0], dict) else {}
+    reason_code = str(first.get("reason_code") or first.get("debt_type") or "")
+    pattern = str(first.get("pattern") or "")
+    file_token = str(first.get("file") or "")
+    severity = str(first.get("severity") or "")
+    parts = ["Guardian gate blocked this tool call"]
+    if reason_code:
+        parts.append(f"reason={reason_code}")
+    if pattern:
+        parts.append(f"pattern={pattern}")
+    if file_token:
+        parts.append(f"file={file_token}")
+    if severity:
+        parts.append(f"severity={severity}")
+    tail = " | ".join(parts)
+    tail += (
+        ". Run nexo_guard_check and nexo_task_open + nexo_cortex_decide "
+        "with explicit evidence before retrying. "
+        "Override per-gate at operator's risk: export NEXO_<GATE>=shadow."
+    )
+    return tail
+
+
+def _has_hard_block(result: dict) -> bool:
+    if not isinstance(result, dict):
+        return False
+    if str(result.get("status") or "") != "blocked":
+        return False
+    blocks = result.get("blocks") or []
+    if not isinstance(blocks, list):
+        return False
+    for block in blocks:
+        if not isinstance(block, dict):
+            continue
+        severity = str(block.get("severity") or "").lower()
+        if severity == "error":
+            return True
+    return False
+
+
+def main() -> int:
+    started = time.time()
+    payload = _read_stdin_json()
+    exit_code = 0
+    summary = "skipped"
+
+    try:
+        sys.path.insert(0, str(_DIR.parent))
+        from hook_guardrails import process_pre_tool_event  # type: ignore
+        result = process_pre_tool_event(payload)
+    except Exception as exc:
+        # Fail-open: never block the tool pipeline on an internal hook
+        # crash. Observability still records the error.
+        summary = f"error:{exc.__class__.__name__}"
+        result = {}
+
+    if _has_hard_block(result):
+        reason = _format_block_reason(result)
+        response = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            },
+        }
+        try:
+            print(json.dumps(response))
+        except Exception:
+            print(json.dumps({
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": "Guardian gate blocked this tool call.",
+                },
+            }))
+        summary = "blocked"
+        exit_code = 0  # JSON response is the canonical path; non-zero is redundant
+
+    elif isinstance(result, dict) and result.get("skipped"):
+        summary = f"skipped:{result.get('reason', '')[:40]}"
+    elif isinstance(result, dict) and str(result.get("status") or "") == "blocked":
+        # Shadow-mode block: debt recorded but tool allowed.
+        summary = "shadow_debt"
+
+    duration_ms = int((time.time() - started) * 1000)
+    _record(duration_ms, exit_code, summary)
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())