nexo-brain 5.3.11 → 5.3.12

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.11",
+  "version": "5.3.12",
   "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

@@ -821,9 +821,7 @@ If you want the shell or Python wrappers instead of raw MCP tools:
 - [docs/reference-verticals.md](docs/reference-verticals.md)
 - [compare/README.md](compare/README.md)
 
-Recommended defaults:
-- Claude Code: `Opus 4.6 with 1M context`
-- Codex: `gpt-5.4` with `xhigh` reasoning
+The model you pick during install is used everywhere — interactive sessions, automation scripts, and all task profiles.  Change it once in your preferences and every part of the system follows.  Default: `Opus 4.6 with 1M context`.
 
 Or use the shell alias created during install (e.g. `atlas`), which now runs `nexo chat .` so it opens the terminal client you pick for that session, with the last-used option shown first.
 
@@ -904,7 +902,7 @@ The Doctor system reads existing health artifacts (immune, watchdog, self-audit)
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
 - **Node.js 18+** (for the installer)
 - **Claude Code is the primary recommended client.** It remains the most mature NEXO path: native hooks, the most battle-tested automation contract, and the clearest parity with historical production behavior.
-- **Recommended profiles:** Claude Code + `Opus 4.6 with 1M context`; Codex + `gpt-5.4` with `xhigh` reasoning if you prefer Codex as your terminal or automation backend.
+- **Model:** You pick your model during install and every component uses it.  Default is `Opus 4.6 with 1M context`.  Scripts and automation profiles read from a single preference — no hardcoded model strings.
 - Python 3, Homebrew, and the selected required client/backend can be installed automatically when NEXO has a supported installer path for that dependency.
 
 ## Architecture
@@ -1021,7 +1019,7 @@ When Claude Desktop is installed, `nexo-brain`, `nexo update`, and `nexo clients
 
 ### Codex
 
-When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop. If selected during install, `nexo chat` can open Codex directly and background automation can also run through Codex. Interactive `nexo chat` launches use Codex's aggressive no-confirmation mode so the session does not stall on repetitive approval prompts. The current recommended Codex profile is `gpt-5.4` with `xhigh` reasoning. Runtime Doctor also audits recent Codex sessions for NEXO startup markers and conditioned-file protocol discipline so parity drift does not hide behind the lack of native Claude-style hooks.
+When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop. If selected during install, `nexo chat` can open Codex directly and background automation can also run through Codex. Interactive `nexo chat` launches use Codex's aggressive no-confirmation mode so the session does not stall on repetitive approval prompts. Codex uses the same model you configured during install — no separate model override is needed. Runtime Doctor also audits recent Codex sessions for NEXO startup markers and conditioned-file protocol discipline so parity drift does not hide behind the lack of native Claude-style hooks.
 
 ### Cursor
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.11",
+  "version": "5.3.12",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — 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",

package/src/agent_runner.py

@@ -509,6 +509,8 @@ def _build_codex_prompt(
         "If that tool is unavailable, call `nexo_guard_check(...)` and `nexo_cortex_check(...)` first.\n"
         "- For long multi-step or cross-session work, call `nexo_workflow_open(...)` and keep it updated with "
         "`nexo_workflow_update(...)` so resume/replay use durable state instead of guesswork.\n"
+        "- Before diagnosing NEXO, explicitly fix the plane first: `product_public`, `runtime_personal`, `installation_live`, `database_real`, or `cooperator`. "
+        "Do not mix planes inside the same diagnosis.\n"
         "- If a target file has conditioned learnings or blocking guard rules, review them before any read/edit/delete step, and acknowledge guard before any edit/delete step.\n"
         "- Do not claim done without explicit verification evidence. Close with `nexo_task_close(...)`; if unavailable, capture the change log and state the evidence explicitly.\n"
         "- When a correction changes the canonical rule, capture or supersede the learning instead of leaving contradictory active rules behind."

package/src/auto_update.py

@@ -36,6 +36,7 @@ TEMPLATE_FILE = REPO_DIR / "templates" / "CLAUDE.md.template"
 
 CHECK_COOLDOWN_SECONDS = 3600  # 1 hour
 GIT_TIMEOUT_SECONDS = 4  # stay well under the 5s total budget
+CRITICAL_BACKUP_TABLES = ("learnings", "session_diary", "guard_checks", "protocol_debt")
 
 
 def _log(msg: str):
@@ -43,6 +44,108 @@ def _log(msg: str):
     print(f"[NEXO auto-update] {msg}", file=sys.stderr)
 
 
+def _critical_table_count(db_path: Path, table: str) -> int | None:
+    """Return COUNT(*) for a critical table when it exists, otherwise None."""
+    import sqlite3
+
+    conn = None
+    try:
+        conn = sqlite3.connect(str(db_path))
+        exists = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name = ?",
+            (table,),
+        ).fetchone()
+        if not exists:
+            return None
+        row = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()
+        return int(row[0]) if row else 0
+    except Exception:
+        return None
+    finally:
+        if conn is not None:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+
+def _find_primary_db_path() -> Path | None:
+    """Return the main nexo.db path if present."""
+    for candidate in (DATA_DIR / "nexo.db", NEXO_HOME / "nexo.db", SRC_DIR / "nexo.db"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _validate_db_backup(source_db: Path, backup_db: Path) -> dict:
+    """Check that a backup preserves non-empty critical tables from the source DB."""
+    report = {
+        "ok": True,
+        "source_db": str(source_db),
+        "backup_db": str(backup_db),
+        "source_counts": {},
+        "backup_counts": {},
+        "regressions": [],
+        "errors": [],
+    }
+    if not source_db.is_file():
+        report["ok"] = False
+        report["errors"].append(f"source db missing: {source_db}")
+        return report
+    if not backup_db.is_file():
+        report["ok"] = False
+        report["errors"].append(f"backup db missing: {backup_db}")
+        return report
+
+    for table in CRITICAL_BACKUP_TABLES:
+        source_count = _critical_table_count(source_db, table)
+        backup_count = _critical_table_count(backup_db, table)
+        report["source_counts"][table] = source_count
+        report["backup_counts"][table] = backup_count
+
+        if source_count is None:
+            continue
+        if backup_count is None:
+            report["regressions"].append({
+                "table": table,
+                "source": source_count,
+                "backup": None,
+                "reason": "missing_in_backup",
+            })
+            continue
+        if source_count > 0 and backup_count == 0:
+            report["regressions"].append({
+                "table": table,
+                "source": source_count,
+                "backup": backup_count,
+                "reason": "critical_rows_lost",
+            })
+
+    if report["regressions"] or report["errors"]:
+        report["ok"] = False
+    return report
+
+
+def _create_validated_db_backup() -> tuple[str | None, dict | None]:
+    """Create a DB backup and validate that critical tables still contain data."""
+    backup_dir = _backup_dbs()
+    if not backup_dir:
+        return None, None
+
+    source_db = _find_primary_db_path()
+    if source_db is None:
+        return backup_dir, None
+
+    report = _validate_db_backup(source_db, Path(backup_dir) / source_db.name)
+    if not report["ok"]:
+        details = ", ".join(
+            f"{item['table']} {item['source']}->{item['backup']}"
+            for item in report["regressions"]
+        ) or "; ".join(report["errors"])
+        _log(f"DB backup validation failed: {details}")
+    return backup_dir, report
+
+
 def _read_last_check() -> dict:
     """Read last check state from disk."""
     try:
@@ -677,6 +780,11 @@ def _check_git_updates() -> str | None:
     if rc != 0:
         return None
 
+    db_backup_dir, backup_report = _create_validated_db_backup()
+    if backup_report is not None and not backup_report["ok"]:
+        _log("Skipping auto-update because the validated pre-update DB backup is not trustworthy.")
+        return None
+
     rc, pull_out, pull_err = _git("pull", "--ff-only")
     if rc != 0:
         _log(f"git pull --ff-only failed: {pull_err}")
@@ -685,9 +793,6 @@ def _check_git_updates() -> str | None:
     new_version = _read_package_version()
     new_req_hash = _requirements_hash()
 
-    # Backup databases before any changes that might run migrations
-    db_backup_dir = _backup_dbs()
-
     # Reinstall pip deps if requirements.txt content changed (not just version)
     if old_req_hash != new_req_hash:
         if not _reinstall_pip_deps():
@@ -2057,7 +2162,14 @@ def manual_sync_update(*, interactive: bool = False, allow_source_pull: bool = T
             pulled = True
 
     _emit_progress(progress_fn, "Creating runtime backups...")
-    db_backup_dir = _backup_dbs()
+    db_backup_dir, backup_report = _create_validated_db_backup()
+    if backup_report is not None and not backup_report["ok"]:
+        return {
+            "ok": False,
+            "mode": "sync",
+            "error": "DB backup validation failed before runtime sync.",
+            "backup_dir": db_backup_dir,
+        }
     tree_backup_dir = _backup_runtime_tree(NEXO_HOME)
     sync_result = {"ok": False, "mode": "sync", "pulled_source": pulled, "backup_dir": db_backup_dir, "tree_backup": tree_backup_dir}
     try:

package/src/cli.py

@@ -26,7 +26,7 @@ Entry points:
   nexo skills evolution [--json]
   nexo clients sync [--json]
   nexo contributor status|on|off [--json]
-  nexo doctor [--tier boot|runtime|deep|all] [--json] [--fix]
+  nexo doctor [--tier boot|runtime|deep|all] [--plane runtime_personal|installation_live|database_real] [--json] [--fix]
   nexo uninstall [--dry-run] [--delete-data] [--json]
 """
 from __future__ import annotations
@@ -1210,7 +1210,7 @@ def _doctor(args):
     init_db()
     tier_label = getattr(args, "tier", "boot") or "boot"
     print(f"[NEXO] Inspecting {tier_label} diagnostics... please wait.", file=sys.stderr, flush=True)
-    report = run_doctor(tier=args.tier, fix=args.fix)
+    report = run_doctor(tier=args.tier, fix=args.fix, plane=getattr(args, "plane", ""))
     output = format_report(report, fmt="json" if args.json else "text")
     print(output)
 
@@ -1749,6 +1749,12 @@ def main():
     doctor_parser = sub.add_parser("doctor", help="Unified diagnostics")
     doctor_parser.add_argument("--tier", default="boot", choices=["boot", "runtime", "deep", "all"],
                                help="Diagnostic tier (default: boot)")
+    doctor_parser.add_argument(
+        "--plane",
+        default="",
+        choices=["", "runtime_personal", "installation_live", "database_real", "product_public", "cooperator"],
+        help="Diagnostic plane. Doctor only runs on runtime_personal, installation_live, or database_real.",
+    )
     doctor_parser.add_argument("--json", action="store_true", help="JSON output")
     doctor_parser.add_argument("--fix", action="store_true", help="Apply deterministic fixes")
 

package/src/client_preferences.py

@@ -48,10 +48,13 @@ INSTALL_PREFERENCE_KEYS = {
 }
 DEFAULT_CLAUDE_CODE_MODEL = "claude-opus-4-6[1m]"
 DEFAULT_CLAUDE_CODE_REASONING_EFFORT = ""
-DEFAULT_CODEX_MODEL = "gpt-5.4"
-DEFAULT_CODEX_REASONING_EFFORT = "xhigh"
-DEFAULT_FAST_MODEL = "gpt-5.4-mini"
-DEFAULT_FAST_REASONING_EFFORT = "medium"
+# Codex/fast defaults: fall back to the user's configured model, not a hardcoded
+# third-party model.  The user picks their model once at install time; every
+# profile and backend should honour that choice.
+DEFAULT_CODEX_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_CODEX_REASONING_EFFORT = ""
+DEFAULT_FAST_MODEL = DEFAULT_CLAUDE_CODE_MODEL
+DEFAULT_FAST_REASONING_EFFORT = ""
 
 
 def _user_home() -> Path:
@@ -260,9 +263,9 @@ def default_automation_task_profiles() -> dict[str, dict[str, str]]:
             "reasoning_effort": "",
         },
         "fast": {
-            "backend": CLIENT_CODEX,
-            "model": DEFAULT_FAST_MODEL,
-            "reasoning_effort": DEFAULT_FAST_REASONING_EFFORT,
+            "backend": "",
+            "model": "",
+            "reasoning_effort": "",
         },
         "balanced": {
             "backend": "",
@@ -523,6 +526,22 @@ def resolve_terminal_client(requested: str | None = None, *, preferences: dict |
     )
 
 
+def resolve_user_model(preferences: dict | None = None) -> str:
+    """Return the single model the user has configured.
+
+    Scripts and automation tasks should call this instead of hardcoding a model
+    string.  The value comes from the user's ``client_runtime_profiles`` for
+    their ``default_terminal_client`` (usually ``claude_code``).
+    """
+    normalized = preferences or load_client_preferences()
+    client = normalize_default_terminal_client(
+        normalized["default_terminal_client"],
+        interactive_clients=normalized["interactive_clients"],
+    )
+    profile = resolve_client_runtime_profile(client, preferences=normalized)
+    return profile["model"]
+
+
 def resolve_automation_backend(preferences: dict | None = None) -> str:
     normalized = preferences or load_client_preferences()
     return normalize_automation_backend(

package/src/client_sync.py

@@ -61,9 +61,10 @@ except Exception:
         }
 
     def resolve_client_runtime_profile(client: str, preferences: dict | None = None) -> dict:
+        _default_model = "claude-opus-4-6[1m]"
         defaults = {
-            "claude_code": {"model": "claude-opus-4-6[1m]", "reasoning_effort": ""},
-            "codex": {"model": "gpt-5.4", "reasoning_effort": "xhigh"},
+            "claude_code": {"model": _default_model, "reasoning_effort": ""},
+            "codex": {"model": _default_model, "reasoning_effort": ""},
         }
         return dict(defaults.get(client, {}))
 

package/src/doctor/orchestrator.py

@@ -6,6 +6,7 @@ import time
 import traceback
 
 from doctor.models import DoctorCheck, DoctorReport
+from doctor.planes import diagnostic_plane_preflight
 from doctor.providers.boot import run_boot_checks
 from doctor.providers.runtime import run_runtime_checks
 from doctor.providers.deep import run_deep_checks
@@ -22,12 +23,13 @@ _TIER_ORDER = ["boot", "runtime", "deep"]
 VALID_TIERS = frozenset(_TIER_ORDER) | {"all"}
 
 
-def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
+def run_doctor(tier: str = "boot", fix: bool = False, plane: str = "") -> DoctorReport:
     """Run diagnostic checks for the specified tier(s).
 
     Args:
         tier: "boot", "runtime", "deep", or "all"
         fix: If True, apply deterministic fixes where possible
+        plane: Explicit diagnostic plane — runtime_personal, installation_live, or database_real
     """
     report = DoctorReport(overall_status="healthy")
     start = time.monotonic()
@@ -44,6 +46,13 @@ def run_doctor(tier: str = "boot", fix: bool = False) -> DoctorReport:
         report.duration_ms = int((time.monotonic() - start) * 1000)
         return report
 
+    _, preflight = diagnostic_plane_preflight(plane)
+    if preflight is not None:
+        report.add(preflight)
+        report.compute_status()
+        report.duration_ms = int((time.monotonic() - start) * 1000)
+        return report
+
     tiers = _TIER_ORDER if tier == "all" else [tier]
 
     for t in tiers:

package/src/doctor/planes.py

@@ -0,0 +1,87 @@
+"""Diagnostic plane preflight for NEXO Doctor."""
+
+from __future__ import annotations
+
+from doctor.models import DoctorCheck
+
+VALID_DIAGNOSTIC_PLANES = {
+    "product_public": {
+        "label": "producto público",
+        "use": "release contracts, artefactos publicados, compare/, docs y surfaces públicas del repo",
+    },
+    "runtime_personal": {
+        "label": "runtime personal",
+        "use": "~/.nexo, scripts personales, followups, reminders y hábitos operativos del operador",
+    },
+    "installation_live": {
+        "label": "instalación viva",
+        "use": "runtime instalado, hooks activos, clientes conectados, cron sync y parity de la instalación local",
+    },
+    "database_real": {
+        "label": "BD real",
+        "use": "SQLite/MySQL reales, filas, schema, deudas, sesiones y evidencia persistida",
+    },
+    "cooperator": {
+        "label": "co-operador",
+        "use": "comportamiento del agente, protocolo, comunicación y decisiones del asistente",
+    },
+}
+
+DOCTOR_COMPATIBLE_PLANES = {"runtime_personal", "installation_live", "database_real"}
+
+
+def normalize_diagnostic_plane(plane: str = "") -> str:
+    clean = (plane or "").strip().lower().replace("-", "_").replace(" ", "_")
+    return clean if clean in VALID_DIAGNOSTIC_PLANES else ""
+
+
+def diagnostic_plane_choices() -> list[str]:
+    return sorted(VALID_DIAGNOSTIC_PLANES)
+
+
+def diagnostic_plane_preflight(plane: str = "") -> tuple[str, DoctorCheck | None]:
+    clean_plane = normalize_diagnostic_plane(plane)
+    if not clean_plane:
+        options = ", ".join(diagnostic_plane_choices())
+        return "", DoctorCheck(
+            id="orchestrator.diagnostic_plane_required",
+            tier="orchestrator",
+            status="critical",
+            severity="error",
+            summary="El diagnóstico está bloqueado hasta fijar explícitamente el plano",
+            evidence=[
+                f"planes válidos: {options}",
+                "Usa `runtime_personal` para ~/.nexo y hábitos del runtime; `installation_live` para hooks/clientes/instalación; `database_real` para filas y schema reales.",
+            ],
+            repair_plan=[
+                "Repite `nexo_doctor` o `nexo doctor` con `plane='runtime_personal'`, `plane='installation_live'` o `plane='database_real'`.",
+                "Si el problema pertenece a producto público o al co-operador, usa el surface correcto en vez de NEXO Doctor.",
+            ],
+            escalation_prompt=(
+                "NEXO mezcló planos en diagnósticos anteriores. El doctor no debe correr hasta que se elija "
+                "explícitamente si el problema está en producto público, runtime personal, instalación viva, BD real o co-operador."
+            ),
+        )
+
+    if clean_plane not in DOCTOR_COMPATIBLE_PLANES:
+        plane_info = VALID_DIAGNOSTIC_PLANES[clean_plane]
+        return clean_plane, DoctorCheck(
+            id="orchestrator.diagnostic_plane_mismatch",
+            tier="orchestrator",
+            status="degraded",
+            severity="warn",
+            summary=f"NEXO Doctor no es la superficie correcta para el plano {plane_info['label']}",
+            evidence=[
+                f"plane: {clean_plane}",
+                f"este plano se diagnostica mejor desde: {plane_info['use']}",
+            ],
+            repair_plan=[
+                "Si quieres diagnosticar runtime/instalación/BD, vuelve a lanzar el doctor con el plano correcto.",
+                "Si el problema es del producto público o del co-operador, usa release checks, repo checks o herramientas de protocolo/sesión en vez de Doctor.",
+            ],
+            escalation_prompt=(
+                "El plano elegido no corresponde al runtime doctor. Cambia de plano o de herramienta antes de seguir para no mezclar diagnóstico técnico con producto o comportamiento del agente."
+            ),
+        )
+
+    return clean_plane, None

package/src/hook_guardrails.py

@@ -14,6 +14,21 @@ from protocol_settings import get_protocol_strictness
 READ_LIKE_TOOLS = {"Read"}
 WRITE_LIKE_TOOLS = {"Edit", "MultiEdit", "Write"}
 DELETE_LIKE_TOOLS = {"Delete"}
+NON_TRIVIAL_PROTOCOL_TOOLS = {"Read", "Bash", "Grep", "Glob", "Edit", "MultiEdit", "Write", "Delete"}
+PROTOCOL_SKIP_TOOLS = {
+    "nexo_startup",
+    "nexo_smart_startup",
+    "nexo_stop",
+    "nexo_heartbeat",
+    "nexo_task_open",
+    "nexo_task_close",
+    "nexo_workflow_open",
+    "nexo_workflow_update",
+    "nexo_guard_check",
+    "nexo_guard_file_check",
+    "nexo_rules_check",
+}
+ACTION_TASK_TYPES = {"edit", "execute", "delegate"}
 NEXO_CODE_ROOT = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent))).expanduser().resolve()
 LIVE_REPO_ROOT = NEXO_CODE_ROOT.parent if NEXO_CODE_ROOT.name == "src" else NEXO_CODE_ROOT
 PUBLIC_REPO_DIRS = {
@@ -50,6 +65,11 @@ def _operation_kind(tool_name: str) -> str:
     return "other"
 
 
+def _short_tool_name(tool_name: str) -> str:
+    clean = str(tool_name or "").strip()
+    return clean.rsplit("__", 1)[-1] if "__" in clean else clean
+
+
 def _normalize_file_path(path: str) -> str:
     return _normalize_path_token(str(Path(path)))
 
@@ -154,7 +174,8 @@ def _resolve_nexo_sid(conn, external_session_id: str) -> str:
 def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
     target = _normalize_file_path(filepath)
     rows = conn.execute(
-        """SELECT task_id, files, guard_has_blocking
+        """SELECT task_id, files, guard_has_blocking, task_type, plan, unknowns,
+                  verification_step, opened_with_guard, must_change_log, must_verify
            FROM protocol_tasks
            WHERE session_id = ? AND status = 'open'
            ORDER BY opened_at DESC""",
@@ -173,7 +194,8 @@ def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
 
 def _find_any_open_task(conn, sid: str) -> dict | None:
     row = conn.execute(
-        """SELECT task_id, files, guard_has_blocking
+        """SELECT task_id, files, guard_has_blocking, task_type, plan, unknowns,
+                  verification_step, opened_with_guard, must_change_log, must_verify
            FROM protocol_tasks
            WHERE session_id = ? AND status = 'open'
            ORDER BY opened_at DESC
@@ -183,6 +205,26 @@ def _find_any_open_task(conn, sid: str) -> dict | None:
     return dict(row) if row else None
 
 
+def _find_any_open_workflow(conn, sid: str) -> dict | None:
+    row = conn.execute(
+        """SELECT run_id, protocol_task_id, current_step_key
+           FROM workflow_runs
+           WHERE session_id = ? AND status IN ('open', 'running', 'blocked', 'waiting_approval')
+           ORDER BY updated_at DESC, run_id DESC
+           LIMIT 1""",
+        (sid,),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def _session_has_guard_check(conn, sid: str) -> bool:
+    row = conn.execute(
+        "SELECT 1 FROM guard_checks WHERE session_id = ? LIMIT 1",
+        (sid,),
+    ).fetchone()
+    return bool(row)
+
+
 def _find_open_debt(conn, *, session_id: str, task_id: str, debt_type: str, file_token: str) -> dict | None:
     row = conn.execute(
         """SELECT *
@@ -241,6 +283,98 @@ def _ensure_protocol_debt(
     )
 
 
+def _task_list_field(task: dict | None, key: str) -> list:
+    if not task:
+        return []
+    try:
+        parsed = json.loads(task.get(key) or "[]")
+    except Exception:
+        return []
+    return parsed if isinstance(parsed, list) else []
+
+
+def _task_needs_workflow(task: dict | None) -> bool:
+    if not task:
+        return False
+    if str(task.get("task_type") or "").strip() not in ACTION_TASK_TYPES:
+        return False
+    if len(_task_list_field(task, "plan")) > 1:
+        return True
+    if len(_task_list_field(task, "unknowns")) > 0:
+        return True
+    if len(_task_list_field(task, "files")) > 1:
+        return True
+    return bool(str(task.get("verification_step") or "").strip())
+
+
+def _append_protocol_warning(warnings: list[dict], message: str) -> None:
+    clean = (message or "").strip()
+    if not clean:
+        return
+    if any((item.get("message") or "").strip() == clean for item in warnings):
+        return
+    warnings.append({"message": clean})
+
+
+def _collect_protocol_warnings(conn, *, sid: str, tool_name: str) -> list[dict]:
+    short_name = _short_tool_name(tool_name)
+    if short_name in PROTOCOL_SKIP_TOOLS or short_name not in NON_TRIVIAL_PROTOCOL_TOOLS:
+        return []
+
+    warnings: list[dict] = []
+    if not sid:
+        _append_protocol_warning(
+            warnings,
+            "Trabajo no trivial detectado antes de `nexo_startup(...)`. Arranca NEXO, abre `nexo_task_open(...)`, y si esto va a durar varias fases abre también `nexo_workflow_open(...)` antes de seguir.",
+        )
+        return warnings
+
+    task = _find_any_open_task(conn, sid)
+    has_guard = _session_has_guard_check(conn, sid)
+    if not task:
+        guard_note = (
+            " Ejecuta `nexo_guard_check(...)` antes de leer código condicionado o compartido."
+            if short_name in {"Read", "Bash", "Grep", "Glob"} and not has_guard
+            else ""
+        )
+        _append_protocol_warning(
+            warnings,
+            "Trabajo no trivial detectado sin `nexo_task_open(...)`. Ábrelo ahora y, si esto va a cruzar varios pasos o mensajes, añade `nexo_workflow_open(...)`." + guard_note,
+        )
+        _append_protocol_warning(
+            warnings,
+            "Recordatorio protocolario: mantén `nexo_heartbeat(...)` al día y no cierres en optimista; si hay cambios reales, registra `nexo_change_log(...)` o cierra con `nexo_task_close(...)` más evidencia.",
+        )
+        return warnings
+
+    task_id = str(task.get("task_id") or "").strip()
+    if str(task.get("task_type") or "").strip() in ACTION_TASK_TYPES and not (task.get("opened_with_guard") or has_guard):
+        _append_protocol_warning(
+            warnings,
+            f"La tarea {task_id} está activa sin guard visible. Ejecuta `nexo_guard_check(...)` antes de tocar código condicionado o compartido.",
+        )
+
+    workflow = _find_any_open_workflow(conn, sid)
+    if _task_needs_workflow(task) and not workflow:
+        _append_protocol_warning(
+            warnings,
+            f"La tarea {task_id} ya tiene pinta de multi-step y sigue sin `nexo_workflow_open(...)`. Ábrelo para que checkpoints, resume y replay no dependan de memoria implícita.",
+        )
+
+    if str(task.get("task_type") or "").strip() in ACTION_TASK_TYPES and short_name in {"Bash", "Edit", "MultiEdit", "Write", "Delete"}:
+        change_note = (
+            " Si editas de verdad y no vas a usar `nexo_task_close(...)` inmediatamente, captura `nexo_change_log(...)`."
+            if task.get("must_change_log")
+            else ""
+        )
+        _append_protocol_warning(
+            warnings,
+            f"Recordatorio protocolario para {task_id}: mantén `nexo_heartbeat(...)` al día y ciérrala con `nexo_task_close(...)` más evidencia antes de decir que está resuelta.{change_note}",
+        )
+
+    return warnings
+
+
 def _collect_automation_live_repo_blocks(
     conn,
     *,
@@ -429,21 +563,20 @@ def process_pre_tool_event(payload: dict) -> dict:
 def process_tool_event(payload: dict) -> dict:
     tool_name = str(payload.get("tool_name", "")).strip()
     op = _operation_kind(tool_name)
-    if op == "other":
-        return {"ok": True, "skipped": True, "reason": "tool not monitored"}
-
     tool_input = payload.get("tool_input")
     files = _extract_touched_files(tool_input)
-    if not files:
-        return {"ok": True, "skipped": True, "reason": "no touched files found"}
-
     conn = get_db()
     sid = _resolve_nexo_sid(conn, str(payload.get("session_id", "")))
-    if not sid:
+    warnings = _collect_protocol_warnings(conn, sid=sid, tool_name=tool_name)
+
+    if op == "other" and not warnings:
+        return {"ok": True, "skipped": True, "reason": "tool not monitored"}
+    if not files and op in {"read", "write", "delete"} and not warnings:
+        return {"ok": True, "skipped": True, "reason": "no touched files found"}
+    if not sid and not warnings:
         return {"ok": True, "skipped": True, "reason": "session not mapped to nexo"}
 
-    conditioned = _load_conditioned_learnings(conn, files)
-    warnings: list[dict] = []
+    conditioned = _load_conditioned_learnings(conn, files) if sid else {}
     violations: list[dict] = []
 
     for filepath in files:
@@ -545,6 +678,9 @@ def format_hook_message(result: dict) -> str:
         return ""
     lines = ["NEXO DISCIPLINE:"]
     for item in result.get("warnings", []):
+        if item.get("message") and not item.get("learning_ids"):
+            lines.append(f"- PROTOCOL REMINDER: {item['message']}")
+            continue
         if item.get("debt_id"):
             lines.append(
                 f"- REVIEW FILE RULES: {item['file']} -> learnings {item['learning_ids']}. "