ultra-builder-pro-cli 0.22.0 → 0.24.0

package/hooks/README.md

@@ -1,16 +1,16 @@
 # Ultra Builder Pro workflow hooks
 
-These hooks observe only Ultra-owned state. Session health/context recognizes an initialized
-`.ultra/.runtime/state.db` and active continuous changes. Direct writes to the MCP-owned Git
-checkpoint and checkout-local projections remain blocked; context, compact, stop, and subagent
-lifecycle behavior is recovery-oriented and does not turn advisory workflow conditions into
-refusal gates.
+These Hooks observe only Ultra-owned state. Session health/context recognizes an
+initialized `.ultra/.runtime/state.db` and reads the canonical Context Envelope.
+Direct writes to the MCP-owned Git checkpoint and checkout-local projections remain
+blocked; context, compact, stop, and agent lifecycle behavior is recovery-oriented and
+does not turn semantic diagnostics into refusal gates.
 
 | Lifecycle | Hook | Purpose |
 |---|---|---|
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
-| Shared helper | `context_spine.py` | Read the latest role/gate/readiness snapshot from state.db and derive one compact breadcrumb |
-| Session start | `workflow_context.py` | Inject the DB-derived breadcrumb with bounded normalized accepted intent, never raw interaction or provider payloads |
+| Shared helper | `context_envelope.py` | Read the same bounded Context Envelope used by MCP, Skills, Sessions, and Workers |
+| Session start | `workflow_context.py` | Inject the compact envelope with accepted intent, never raw interaction or provider payloads |
 | Before edit | `active_task_context.py` | Protect `.ultra/tasks/tasks.json` (Git team checkpoint) and `.ultra/.runtime/projections/tasks.json` (local view), then restate the same DB-derived task breadcrumb |
 | Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
 | After compact/resume | `workflow_resume.py` | Prefer the DB breadcrumb; restore the minimal file checkpoint only when no active change owns recovery |
@@ -27,7 +27,7 @@ memory and graph content belongs to separately installed providers.
 `subagent_started` or `subagent_stopped` to `state.db`; it never stores transcript
 paths, messages, or a parallel JSONL lifecycle log.
 
-`context_spine.py` is an imported library, not an eighth lifecycle registration.
+`context_envelope.py` is an imported library, not an additional lifecycle registration.
 Registering it separately would duplicate hook execution. The checkpoint is a recovery artifact, not a second authority. A valid newer
 live workflow wins; a newer valid checkpoint may restore a missing or older
 live file; corrupt, non-object, or terminal checkpoints are ignored.
@@ -37,3 +37,6 @@ Runtime wiring:
 - Claude Code: native `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` paths.
 - Codex: native `hooks/hooks.json` through `hooks/adapters/codex.py` for wire normalization.
 - OpenCode: native JavaScript plugin events; the Python hook suite is not copied.
+- Kimi Code: native lifecycle events through its wire adapter.
+- Grok Build: camelCase lifecycle events; ignored stdout channels are used for
+  observation only, and every Skill rereads authoritative Context at entry.

package/hooks/active_task_context.py

@@ -1,15 +1,15 @@
 #!/usr/bin/env python3
-"""Protect Ultra managed task files and restate the active workflow boundary."""
+"""Protect managed task files and restate the live Ultra Context Envelope."""
 
 import json
 import sys
 from pathlib import Path
 
-from context_spine import (
-    ContextSpineError,
+from context_envelope import (
+    ContextEnvelopeError,
     find_root,
-    read_breadcrumb,
-    render_breadcrumb,
+    read_context_envelope,
+    render_context_envelope,
 )
 
 TEAM_TASK_LEDGER = Path(".ultra/tasks/tasks.json")
@@ -86,7 +86,7 @@ def main() -> None:
     for target_root in managed_roots(data, start):
         try:
             target_authority = find_root(target_root)
-        except ContextSpineError as exc:
+        except ContextEnvelopeError as exc:
             print(json.dumps(managed_file_denial(
                 "Refusing a direct write to an MCP-managed Ultra task file while the "
                 f"runtime authority is conflicted: {exc}. Resolve the "
@@ -100,13 +100,13 @@ def main() -> None:
             "Refusing a direct write to an MCP-managed Ultra task file. "
             ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
             ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
-            "Use the Ultra MCP task or task.ledger tools."
+            "Use ultra.record for task contracts/outcomes and ultra.sync for the team checkpoint."
         )))
         return
 
     try:
         root = find_root(start)
-    except ContextSpineError as exc:
+    except ContextEnvelopeError as exc:
         print(
             f"[active_task_context] cannot resolve Ultra root: {exc}",
             file=sys.stderr,
@@ -119,7 +119,7 @@ def main() -> None:
                 "Refusing a direct write to an MCP-managed Ultra task file while the "
                 f"runtime authority is conflicted: {exc}. Resolve the "
                 "state.db conflict with ultra-doctor before retrying the owning "
-                "MCP operation."
+                "public Ultra operation."
             )))
             return
         root = None
@@ -131,18 +131,18 @@ def main() -> None:
                 "Refusing a direct write to an MCP-managed Ultra task file. "
                 ".ultra/tasks/tasks.json is the MCP-published team checkpoint and "
                 ".ultra/.runtime/projections/tasks.json is the checkout-local DB view. "
-                "Use the Ultra MCP task or task.ledger tools."
+                "Use ultra.record for task contracts/outcomes and ultra.sync for the team checkpoint."
         )))
         return
     try:
-        breadcrumb = read_breadcrumb(root)
-    except ContextSpineError as exc:
-        print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
-        breadcrumb = None
-    if breadcrumb and breadcrumb.get("workflow"):
+        envelope = read_context_envelope(root)
+    except ContextEnvelopeError as exc:
+        print(f"[active_task_context] cannot inspect Context Envelope: {exc}", file=sys.stderr)
+        envelope = None
+    if envelope:
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
-            "additionalContext": render_breadcrumb(root, breadcrumb),
+            "additionalContext": render_context_envelope(root, envelope),
         }}))
         return
     print(json.dumps({}))

package/hooks/adapters/grok.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Grok Build wire adapter for Ultra observational lifecycle hooks."""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+HOOK_ROOT = Path(__file__).resolve().parent.parent
+ALLOWED_FEATURES = {
+    "active_task_context.py",
+    "health_check.py",
+    "pre_stop_check.py",
+    "subagent_tracker.py",
+    "workflow_checkpoint.py",
+}
+
+
+def normalize_input(payload: dict[str, Any]) -> dict[str, Any]:
+    """Translate Grok's camelCase wire names into the shared hook contract."""
+    normalized = copy.deepcopy(payload)
+    aliases = {
+        "hookEventName": "hook_event_name",
+        "sessionId": "session_id",
+        "toolName": "tool_name",
+        "toolInput": "tool_input",
+        "toolResult": "tool_output",
+        "stopHookActive": "stop_hook_active",
+        "agentId": "agent_id",
+        "agentType": "agent_type",
+        "workspaceRoot": "workspace_root",
+    }
+    for source, target in aliases.items():
+        if source in normalized and target not in normalized:
+            normalized[target] = normalized[source]
+    return normalized
+
+
+def _parse_output(stdout: str) -> dict[str, Any]:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def adapt_output(output: dict[str, Any], event: str, reason: str | None) -> dict[str, Any]:
+    """Return only output fields Grok actually consumes for this event."""
+    if event == "PreToolUse":
+        specific = output.get("hookSpecificOutput")
+        specific = specific if isinstance(specific, dict) else {}
+        if specific.get("permissionDecision") == "deny":
+            return {
+                "decision": "deny",
+                "reason": str(
+                    specific.get("permissionDecisionReason")
+                    or "Ultra refused a direct write to a managed authority file"
+                ),
+            }
+        return {"decision": "allow"}
+    # Ultra Stop is advisory. Grok's session-end Stop is observe-only and must
+    # never be confused with a genuine end_turn gate.
+    if event == "Stop" and reason != "end_turn":
+        return {}
+    return {}
+
+
+def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str]) -> dict[str, Any]:
+    if feature not in ALLOWED_FEATURES or Path(feature).name != feature:
+        return {}
+    script = HOOK_ROOT / feature
+    if not script.is_file():
+        return {}
+    normalized = normalize_input(payload)
+    env = os.environ.copy()
+    env["UBP_HOOK_RUNTIME"] = "grok"
+    plugin_data = env.get("GROK_PLUGIN_DATA") or env.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        env["UBP_HOOK_DATA"] = plugin_data
+    cwd = normalized.get("cwd")
+    run_cwd = str(cwd) if isinstance(cwd, str) and Path(cwd).is_dir() else os.getcwd()
+    proc = subprocess.run(
+        [sys.executable, str(script), *feature_args],
+        input=json.dumps(normalized),
+        text=True,
+        capture_output=True,
+        cwd=run_cwd,
+        env=env,
+        timeout=30,
+        check=False,
+    )
+    if proc.stderr:
+        print(proc.stderr.rstrip(), file=sys.stderr)
+    if proc.returncode != 0:
+        return {}
+    return adapt_output(
+        _parse_output(proc.stdout),
+        str(payload.get("hookEventName") or ""),
+        str(payload.get("reason") or "") or None,
+    )
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(json.dumps({}))
+        return 0
+    feature = sys.argv[1]
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if not isinstance(payload, dict):
+            payload = {}
+    except json.JSONDecodeError as exc:
+        print(f"[grok hook] invalid input: {exc}", file=sys.stderr)
+        payload = {}
+    try:
+        output = run_feature(feature, payload, sys.argv[2:])
+    except Exception as exc:
+        print(f"[grok hook] {feature} failed open: {exc}", file=sys.stderr)
+        output = {}
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/{context_spine.py → context_envelope.py}

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Thin bridge to the single bundled JavaScript Context Spine reader."""
+"""Thin read-only bridge to the bundled Ultra Context Envelope reader."""
 
 import json
 import os
@@ -11,12 +11,12 @@ from pathlib import Path
 from runtime_paths import RuntimePathError, find_project_root
 
 
-class ContextSpineError(RuntimeError):
-    """The canonical breadcrumb helper could not be executed or decoded."""
+class ContextEnvelopeError(RuntimeError):
+    """The canonical Context Envelope helper could not be executed or decoded."""
 
 
-class Breadcrumb(dict):
-    """Dictionary breadcrumb carrying its canonical rendered injection text."""
+class ContextEnvelope(dict):
+    """Dictionary envelope carrying its canonical bounded injection text."""
 
     def __init__(self, value: dict, rendered: str):
         super().__init__(value)
@@ -27,27 +27,27 @@ def find_root(start: Path):
     try:
         return find_project_root(start)
     except RuntimePathError as exc:
-        raise ContextSpineError(str(exc)) from exc
+        raise ContextEnvelopeError(str(exc)) from exc
 
 
 def find_root_for_hook(start: Path, hook_name: str):
     """Fail open at a hook boundary while preserving path-conflict evidence."""
     try:
         return find_root(start)
-    except ContextSpineError as exc:
+    except ContextEnvelopeError as exc:
         print(f"[{hook_name}] cannot resolve Ultra root: {exc}", file=sys.stderr)
         return None
 
 
 def _helper_path() -> Path:
     hook_root = Path(__file__).resolve().parent
-    installed = hook_root.parent / "runtime" / "breadcrumb.cjs"
+    installed = hook_root.parent / "runtime" / "hook-context.cjs"
     if installed.is_file():
         return installed
-    source = hook_root.parent / "mcp-server" / "breadcrumb.cjs"
+    source = hook_root.parent / "mcp-server" / "hook-context.cjs"
     if source.is_file():
         return source
-    raise ContextSpineError("bundled breadcrumb helper is missing")
+    raise ContextEnvelopeError("bundled Context Envelope helper is missing")
 
 
 def _node_binary() -> str:
@@ -57,10 +57,10 @@ def _node_binary() -> str:
     discovered = shutil.which("node")
     if discovered:
         return discovered
-    raise ContextSpineError("node executable is unavailable")
+    raise ContextEnvelopeError("node executable is unavailable")
 
 
-def read_breadcrumb(root: Path):
+def read_context_envelope(root: Path):
     try:
         result = subprocess.run(
             [_node_binary(), str(_helper_path()), str(root.resolve())],
@@ -70,27 +70,31 @@ def read_breadcrumb(root: Path):
             timeout=5,
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
-        raise ContextSpineError(str(exc)) from exc
+        raise ContextEnvelopeError(str(exc)) from exc
     if result.returncode != 0:
         detail = result.stderr.strip() or f"exit {result.returncode}"
-        raise ContextSpineError(detail)
+        raise ContextEnvelopeError(detail)
     try:
         payload = json.loads(result.stdout)
     except json.JSONDecodeError as exc:
-        raise ContextSpineError(f"invalid breadcrumb response: {exc}") from exc
+        raise ContextEnvelopeError(f"invalid Context Envelope response: {exc}") from exc
     if not isinstance(payload, dict):
-        raise ContextSpineError("breadcrumb response must be an object")
-    value = payload.get("breadcrumb")
+        raise ContextEnvelopeError("Context Envelope response must be an object")
+    value = payload.get("context")
     if value is None:
         return None
     rendered = payload.get("text")
     if not isinstance(value, dict) or not isinstance(rendered, str) or not rendered:
-        raise ContextSpineError("breadcrumb response is missing canonical state or text")
-    return Breadcrumb(value, rendered)
+        raise ContextEnvelopeError(
+            "Context Envelope response is missing canonical state or text"
+        )
+    return ContextEnvelope(value, rendered)
 
 
-def render_breadcrumb(_root: Path, breadcrumb: dict) -> str:
-    rendered = getattr(breadcrumb, "rendered", None)
+def render_context_envelope(_root: Path, context: dict) -> str:
+    rendered = getattr(context, "rendered", None)
     if not isinstance(rendered, str) or not rendered:
-        raise ContextSpineError("breadcrumb was not produced by the canonical reader")
+        raise ContextEnvelopeError(
+            "Context Envelope was not produced by the canonical reader"
+        )
     return rendered

package/hooks/health_check.py

@@ -6,7 +6,11 @@ import sqlite3
 import sys
 from pathlib import Path
 
-from context_spine import ContextSpineError, find_root_for_hook, read_breadcrumb
+from context_envelope import (
+    ContextEnvelopeError,
+    find_root_for_hook,
+    read_context_envelope,
+)
 from runtime_paths import state_db_path
 
 
@@ -14,8 +18,9 @@ REQUIRED_TABLES = {
     "baselines",
     "tasks", "events", "sessions", "schema_version", "migration_history",
     "telemetry", "specs_refs", "circuit_breaker", "changes", "artifacts",
-    "context_snapshots", "spec_learning_candidates", "trace_links", "incidents", "projection_jobs",
-    "event_consumers", "workflow_runs", "workflow_steps",
+    "artifact_edges", "context_snapshots", "spec_learning_candidates", "trace_links",
+    "incidents", "projection_jobs", "event_consumers", "stage_checkpoints",
+    "decision_records", "context_envelopes", "worker_packets",
 }
 
 
@@ -28,22 +33,6 @@ def hook_input() -> dict:
         return {}
 
 
-def has_active_workflow(db_path: Path) -> bool:
-    if not db_path.is_file():
-        return False
-    try:
-        uri = f"file:{db_path}?mode=ro"
-        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
-            row = conn.execute(
-                """SELECT 1 FROM workflow_runs
-                   WHERE status IN ('active', 'blocked', 'ready')
-                   LIMIT 1"""
-            ).fetchone()
-            return row is not None
-    except sqlite3.Error:
-        return False
-
-
 def inspect(root: Path) -> dict:
     db_path = state_db_path(root)
     report = {"status": "healthy", "project": str(root), "checks": {}}
@@ -54,8 +43,8 @@ def inspect(root: Path) -> dict:
         return report
 
     try:
-        breadcrumb = read_breadcrumb(root)
-    except ContextSpineError as exc:
+        context = read_context_envelope(root)
+    except ContextEnvelopeError as exc:
         report["checks"]["authority"] = {"status": "fail", "reason": str(exc)}
         report["status"] = "degraded"
         return report
@@ -82,14 +71,18 @@ def inspect(root: Path) -> dict:
                 report["status"] = "degraded"
                 return report
 
+            envelope = context.get("envelope", {}) if context else {}
+            diagnostics = envelope.get("diagnostics", {})
             baseline_codes = [
-                code for code in [
-                    *(breadcrumb.get("blockers", []) if breadcrumb else []),
-                    *(breadcrumb.get("warnings", []) if breadcrumb else []),
+                str(item.get("code"))
+                for item in [
+                    *diagnostics.get("needs_attention", []),
+                    *diagnostics.get("warnings", []),
+                    *diagnostics.get("hard_conflicts", []),
                 ]
-                if str(code).startswith("BASELINE_")
+                if str(item.get("code", "")).startswith("BASELINE_")
             ]
-            baseline = breadcrumb.get("baseline") if breadcrumb else None
+            baseline = envelope.get("baseline")
             baseline_is_ready = isinstance(baseline, dict) and baseline.get("status") == "ready"
             baseline_status = (
                 "fail" if baseline_codes and baseline_is_ready
@@ -188,9 +181,6 @@ def main() -> None:
     if root is None:
         print(json.dumps({}))
         return
-    if not has_active_workflow(state_db_path(root)):
-        print(json.dumps({}))
-        return
     report = inspect(root)
     if report["status"] != "healthy":
         print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)

package/hooks/pre_stop_check.py

@@ -5,7 +5,11 @@ import json
 import sys
 from pathlib import Path
 
-from context_spine import ContextSpineError, find_root_for_hook, read_breadcrumb
+from context_envelope import (
+    ContextEnvelopeError,
+    find_root_for_hook,
+    read_context_envelope,
+)
 
 
 def allow_stop() -> None:
@@ -32,21 +36,27 @@ def main() -> None:
         allow_stop()
         return
     try:
-        breadcrumb = read_breadcrumb(root)
-    except ContextSpineError as exc:
-        print(f"[pre_stop_check] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        context = read_context_envelope(root)
+    except ContextEnvelopeError as exc:
+        print(f"[pre_stop_check] cannot inspect Context Envelope: {exc}", file=sys.stderr)
         allow_stop()
         return
-    if breadcrumb and breadcrumb.get("workflow"):
-        allowed = ", ".join(breadcrumb.get("allowed_transitions") or []) or "none"
-        required = breadcrumb.get("required_transition") or "none"
+    envelope = context.get("envelope", {}) if context else {}
+    change = envelope.get("change") or {}
+    task = envelope.get("task") or {}
+    if change.get("id") and change.get("status") not in ("archived", "cancelled"):
+        attention = envelope.get("diagnostics", {}).get("needs_attention", [])
+        warnings = envelope.get("diagnostics", {}).get("warnings", [])
+        codes = ", ".join(
+            str(item.get("code")) for item in [*attention, *warnings] if item.get("code")
+        ) or "none"
         print(
             "[Ultra stop advisory] Active Ultra change remains open: "
-            f"change={breadcrumb['change_id']}, "
-            f"task={breadcrumb.get('task_id') or 'none'}, "
-            f"gate={breadcrumb.get('gate') or 'alignment'}, "
-            f"allowed_transitions={allowed}, required_transition={required}. "
-            "Stop is allowed; resume or explicitly archive the change later.",
+            f"change={change['id']}, "
+            f"task={task.get('id') or 'none'}, "
+            f"stage={envelope.get('execution', {}).get('stage') or 'project'}, "
+            f"diagnostics={codes}. "
+            "Stop is allowed; read ultra.context before resuming or explicitly archive later.",
             file=sys.stderr,
         )
     allow_stop()

package/hooks/subagent_tracker.py

@@ -13,7 +13,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from context_spine import find_root_for_hook
+from context_envelope import find_root_for_hook
 
 
 def helper_path() -> Path:

package/hooks/workflow_checkpoint.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Write a recovery projection of the canonical DB breadcrumb before compaction."""
+"""Write an advisory recovery copy of the live Context Envelope before compaction."""
 
 import json
 import os
@@ -8,11 +8,11 @@ import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
-from context_spine import (
-    ContextSpineError,
+from context_envelope import (
+    ContextEnvelopeError,
     find_root_for_hook,
-    read_breadcrumb,
-    render_breadcrumb,
+    read_context_envelope,
+    render_context_envelope,
 )
 from runtime_paths import RuntimePathError, validate_project_layout
 
@@ -32,12 +32,12 @@ def main() -> None:
         print(json.dumps({}))
         return
     try:
-        breadcrumb = read_breadcrumb(root)
-    except ContextSpineError as exc:
-        print(f"[workflow_checkpoint] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        envelope = read_context_envelope(root)
+    except ContextEnvelopeError as exc:
+        print(f"[workflow_checkpoint] cannot inspect Context Envelope: {exc}", file=sys.stderr)
         print(json.dumps({}))
         return
-    if not breadcrumb or not breadcrumb.get("workflow"):
+    if not envelope:
         print(json.dumps({}))
         return
 
@@ -53,11 +53,12 @@ def main() -> None:
     runtime_dir = root / ".ultra" / ".runtime"
     runtime_dir.mkdir(parents=True, exist_ok=True)
     checkpoint = {
-        "schema": 2,
+        "schema": 3,
         "captured_at": datetime.now(timezone.utc).isoformat(),
         "session_id": data.get("session_id", ""),
-        "breadcrumb": dict(breadcrumb),
-        "rendered": render_breadcrumb(root, breadcrumb),
+        "context_digest": envelope.get("digest"),
+        "context": dict(envelope),
+        "rendered": render_context_envelope(root, envelope),
     }
     fd, temp_name = tempfile.mkstemp(prefix="checkpoint.", suffix=".json", dir=runtime_dir)
     try:
@@ -68,7 +69,7 @@ def main() -> None:
     finally:
         if os.path.exists(temp_name):
             os.unlink(temp_name)
-    print(json.dumps({"systemMessage": "Ultra workflow checkpoint saved."}))
+    print(json.dumps({"systemMessage": "Ultra Context Envelope checkpoint saved."}))
 
 
 if __name__ == "__main__":

package/hooks/workflow_context.py

@@ -1,15 +1,15 @@
 #!/usr/bin/env python3
-"""Inject one compact Ultra workflow-memory position without provider payloads."""
+"""Inject one compact, read-only Ultra Context Envelope."""
 
 import json
 import sys
 from pathlib import Path
 
-from context_spine import (
-    ContextSpineError,
+from context_envelope import (
+    ContextEnvelopeError,
     find_root_for_hook,
-    read_breadcrumb,
-    render_breadcrumb,
+    read_context_envelope,
+    render_context_envelope,
 )
 
 
@@ -32,15 +32,14 @@ def main() -> None:
         print(json.dumps({}))
         return
     try:
-        breadcrumb = read_breadcrumb(root)
-    except ContextSpineError as exc:
-        print(f"[workflow_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
-        breadcrumb = None
-    if breadcrumb and breadcrumb.get("workflow"):
-        context = render_breadcrumb(root, breadcrumb)
-    else:
+        envelope = read_context_envelope(root)
+    except ContextEnvelopeError as exc:
+        print(f"[workflow_context] cannot inspect Context Envelope: {exc}", file=sys.stderr)
+        envelope = None
+    if not envelope:
         print(json.dumps({}))
         return
+    context = render_context_envelope(root, envelope)
     print(json.dumps({"hookSpecificOutput": {
         "hookEventName": "SessionStart",
         "additionalContext": context,