@jaguilar87/gaia 5.0.10 → 5.0.11

package/dist/gaia-ops/hooks/adapters/host_session.py

@@ -0,0 +1,53 @@
+"""
+Host Session ID Access for Gaia-Ops.
+
+Adapter-owned utility that encapsulates how the host CLI exposes the current
+session identifier via the environment. The host-specific env var name lives
+ONLY here (inside ``hooks/adapters/``); business logic modules call these
+helpers instead of reading the environment directly, so the core stays
+agnostic to the host CLI's session-propagation convention.
+
+Mirrors the ``channel.py`` pattern: a small standalone module under
+``adapters/`` that reads a host env var and is imported by business logic,
+with no dependency on the heavier ``ClaudeCodeAdapter`` (avoids any
+circular-import or instantiation concern in low-level modules).
+"""
+
+import hashlib
+import logging
+import os
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+# The environment variable the host CLI (Claude Code) uses to advertise the
+# current session id. Confined to this adapter module by design.
+_HOST_SESSION_ENV_VAR = "CLAUDE_SESSION_ID"
+
+
+def read_host_session_id(default: str = "default") -> str:
+    """Return the host session id from the environment, or ``default``.
+
+    The host CLI does not guarantee the session env var is exported into a
+    hook subprocess. Callers that have the parsed stdin event in hand should
+    prefer the event's ``session_id`` and use this only as a fallback.
+    """
+    return os.environ.get(_HOST_SESSION_ENV_VAR, default)
+
+
+def get_or_create_host_session_id() -> str:
+    """Return the host session id, generating and storing one if absent.
+
+    Checks the host session env var first. If absent, generates a new id from
+    the current time and PID, stores it back into the env var (so subsequent
+    reads in the same process are stable), and returns it.
+    """
+    session_id = os.environ.get(_HOST_SESSION_ENV_VAR)
+    if not session_id:
+        timestamp = datetime.now().strftime("%H%M%S")
+        hash_input = f"{timestamp}-{os.getpid()}"
+        session_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
+        session_id = f"session-{timestamp}-{session_hash}"
+        os.environ[_HOST_SESSION_ENV_VAR] = session_id
+        logger.debug("Generated new session_id: %s", session_id)
+    return session_id

package/dist/gaia-ops/hooks/adapters/host_transcript.py

@@ -0,0 +1,75 @@
+"""
+Host Transcript Access for Gaia-Ops.
+
+Adapter-owned utility that encapsulates how the host CLI (Claude Code) persists
+a subagent transcript on disk. The host-specific format -- a JSONL file whose
+lines are JSON objects with the role/content nested inside a ``message`` field
+-- lives ONLY here (inside ``hooks/adapters/``). Business logic modules iterate
+over normalized ``(role, content)`` entries via :func:`iter_transcript_entries`
+instead of opening the file and calling ``json.loads`` themselves, so the core
+stays agnostic to the host CLI's transcript-serialization convention.
+
+Mirrors the ``host_session.py`` pattern: a small standalone module under
+``adapters/`` that owns a single host-specific detail and is imported by
+business logic, with no dependency on the heavier ``ClaudeCodeAdapter`` (avoids
+any circular-import or instantiation concern in low-level modules).
+
+If a future host advertises its transcript in a different shape (e.g. a single
+JSON array, or a different nesting), only this module changes; the readers in
+``modules/agents/transcript_reader.py`` keep iterating normalized entries.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Iterator, Tuple
+
+logger = logging.getLogger(__name__)
+
+# A normalized transcript entry as seen by business logic: (role, content).
+# ``content`` is the raw host content -- a str, a list of content blocks, or
+# None -- left for the reader to normalize per its own needs.
+TranscriptEntry = Tuple[str, object]
+
+
+def iter_transcript_entries(transcript_path: str) -> Iterator[TranscriptEntry]:
+    """Yield ``(role, content)`` for each message entry in the host transcript.
+
+    Encapsulates the host CLI's transcript format: the file at
+    ``transcript_path`` is JSONL (one JSON object per line); each object nests
+    the role/content inside a ``message`` field, falling back to the object
+    itself for a flat ``{role, content}`` shape. Lines that are blank or fail
+    to parse as JSON are skipped silently so a partially-written transcript
+    never crashes a hook.
+
+    Performs path expansion (``~``) and an existence check. A missing/empty
+    path or a nonexistent file yields nothing. Callers receive a uniform
+    stream of normalized entries and never see JSONL or ``json.loads``.
+    """
+    if not transcript_path:
+        return
+    try:
+        path = Path(transcript_path).expanduser()
+        if not path.exists():
+            logger.debug("Transcript file not found: %s", path)
+            return
+        with open(path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+                if not isinstance(entry, dict):
+                    continue
+                # Host format: role/content nested inside ``message``; fall
+                # back to the entry itself for a flat shape.
+                msg = entry.get("message", entry)
+                if not isinstance(msg, dict):
+                    continue
+                yield msg.get("role", ""), msg.get("content", "")
+    except Exception as e:  # pragma: no cover - defensive, never crash a hook
+        logger.debug("Failed to read transcript from %s: %s", transcript_path, e)
+        return

package/dist/gaia-ops/hooks/adapters/registry.py

@@ -0,0 +1,87 @@
+"""
+Adapter Registry / Factory for Gaia-Ops Hooks.
+
+The single construction point for the host :class:`HookAdapter`. Every entry
+point (``pre_tool_use``, ``post_tool_use``, ``stop_hook``, ``subagent_start``,
+``subagent_stop``, ``task_completed``, ``hook_entry``) and the shared
+``hook_response`` builder obtain their adapter through :func:`get_adapter`
+instead of calling ``ClaudeCodeAdapter()`` directly. Concentrating the
+``ClaudeCodeAdapter`` reference here means the core never names a concrete host
+class at a call site (AC-5): supporting a new host is a one-line
+:func:`register_adapter` call, not an edit to every entry point one by one
+(AC-7 / brief #88 "Desacoplar la lógica de Gaia de Claude Code").
+
+Mirrors the ``channel.py`` / ``host_session.py`` / ``host_transcript.py``
+pattern: a small standalone module under ``adapters/`` that owns a single
+host-coupling concern -- here, *which adapter class to build* -- and is imported
+by callers. The adapter is stateless (no ``__init__``, no mutable instance
+attributes), so a single cached instance is shared process-wide; this matches
+the long-standing module-level ``_adapter = ClaudeCodeAdapter()`` singleton in
+``modules/tools/hook_response.py`` that this registry now subsumes.
+
+Host selection
+--------------
+The active host is keyed by :data:`DEFAULT_HOST` (``"claude_code"``). A future
+host registers its class and, when more than one is installed, ``get_adapter``
+can be extended to resolve the key from a host-detection signal -- without any
+entry point changing.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Type
+
+from .base import HookAdapter
+from .claude_code import ClaudeCodeAdapter
+
+# The only host Gaia ships an adapter for today. Confined to this module so the
+# concrete class name appears at exactly one call site in the whole core.
+DEFAULT_HOST = "claude_code"
+
+# host key -> adapter class. A new host appends one entry here (or via
+# register_adapter); nothing else in the codebase references the class.
+_REGISTRY: Dict[str, Type[HookAdapter]] = {
+    DEFAULT_HOST: ClaudeCodeAdapter,
+}
+
+# Cache of constructed adapters, keyed by host. The adapter is stateless, so a
+# single instance per host is reused for the life of the process.
+_INSTANCES: Dict[str, HookAdapter] = {}
+
+
+def register_adapter(host: str, adapter_cls: Type[HookAdapter]) -> None:
+    """Register ``adapter_cls`` as the adapter for host key ``host``.
+
+    Supporting a new host CLI is this call plus the new ``HookAdapter``
+    subclass -- no entry point changes. Re-registering a host replaces the
+    class and drops any cached instance so the next :func:`get_adapter` builds
+    the new one.
+
+    Raises:
+        TypeError: If ``adapter_cls`` is not a ``HookAdapter`` subclass.
+    """
+    if not (isinstance(adapter_cls, type) and issubclass(adapter_cls, HookAdapter)):
+        raise TypeError(
+            f"adapter_cls must be a HookAdapter subclass, got {adapter_cls!r}"
+        )
+    _REGISTRY[host] = adapter_cls
+    _INSTANCES.pop(host, None)
+
+
+def get_adapter(host: Optional[str] = None) -> HookAdapter:
+    """Return the shared :class:`HookAdapter` instance for ``host``.
+
+    The single construction point for the host adapter. Lazily builds and
+    caches one instance per host (the adapter is stateless, so the instance is
+    safe to share). Defaults to :data:`DEFAULT_HOST` when ``host`` is omitted.
+
+    Raises:
+        KeyError: If ``host`` has no registered adapter class.
+    """
+    key = host or DEFAULT_HOST
+    instance = _INSTANCES.get(key)
+    if instance is None:
+        adapter_cls = _REGISTRY[key]
+        instance = adapter_cls()
+        _INSTANCES[key] = instance
+    return instance

package/dist/gaia-ops/hooks/adapters/types.py

@@ -59,11 +59,70 @@ class PermissionDecision(enum.Enum):
     ASK = "ask"
 
 
-class DistributionChannel(enum.Enum):
-    """How gaia-ops was installed and is being invoked."""
+@dataclass(frozen=True)
+class HostDistribution:
+    """How a host distributes and invokes gaia-ops -- declared by the adapter.
+
+    The CLI-agnostic value object that replaces a core-owned enumeration of
+    distribution channels. The core never enumerates a host's channels nor
+    names a host-specific "root"; it carries an opaque :class:`HostDistribution`
+    that the concrete adapter PRODUCES from its own distribution model (see
+    :meth:`HookAdapter.detect_distribution`). A host with a distribution model
+    the core has never heard of declares it here without any change to the core
+    vocabulary -- the same seam established for capabilities
+    (:class:`HostCapability`) and consent (:class:`ConsentRequest`).
+
+    The concrete channel names (Claude Code's "npm" / "plugin") and the meaning
+    of ``root`` (Claude Code's plugin root) live ONLY in the host's adapter; the
+    core treats both as opaque values.
+
+    Fields:
+        channel: The host's own opaque channel identifier (e.g. Claude Code
+            uses "npm" / "plugin"). The core compares or logs it but never
+            branches on a value it enumerated -- the host owns the vocabulary.
+        root: The distribution root for this channel when the host has the
+            notion of one (Claude Code: the plugin root directory); ``None``
+            when the channel has no such root. The core does not interpret it.
+    """
 
-    NPM = "npm"
-    PLUGIN = "plugin"
+    channel: str
+    root: Optional[Path] = None
+
+
+class HostCapability(enum.Enum):
+    """A named capability a host (CLI backend) may or may not offer.
+
+    The CLI-agnostic vocabulary business logic uses to ASK a host whether it
+    can do a thing -- without naming any host. Each concrete adapter DECLARES
+    which of these it supports (see :meth:`HookAdapter.capabilities`); the core
+    queries that declaration via :meth:`HookAdapter.supports` and, when a
+    capability is absent, degrades in a *declared* way (a
+    :class:`CapabilityDegradation`) rather than crashing or branching on the
+    host's identity. Claude Code supports all of these today; a future host
+    (Codex, Antigravity) that lacks one drives the degradation path.
+
+    Members:
+        INTERACTIVE_CONSENT: the host can gather the user's consent inline,
+            in-session (Claude Code: the native AskUserQuestion prompt).
+        OUT_OF_BAND_APPROVAL: the host can run an approval cycle keyed to a
+            persisted identifier the decision is later matched against
+            (Claude Code: the orchestrator approval-id hand-off).
+        STRUCTURED_PERMISSION_DECISION: the host accepts a structured
+            allow/deny/ask permission decision (vs. only an exit code).
+        UPDATED_INPUT: the host can apply adapter-modified tool input
+            transparently (e.g. a footer-stripped command).
+        CONTEXT_INJECTION: the host can inject additional context into the
+            session at hook time (SessionStart / SubagentStart context).
+        TRANSCRIPT_ACCESS: the host exposes the agent transcript for
+            post-hoc inspection (contract / anomaly analysis).
+    """
+
+    INTERACTIVE_CONSENT = "interactive_consent"
+    OUT_OF_BAND_APPROVAL = "out_of_band_approval"
+    STRUCTURED_PERMISSION_DECISION = "structured_permission_decision"
+    UPDATED_INPUT = "updated_input"
+    CONTEXT_INJECTION = "context_injection"
+    TRANSCRIPT_ACCESS = "transcript_access"
 
 
 @dataclass(frozen=True)
@@ -71,13 +130,18 @@ class HookEvent:
     """Normalized hook event, CLI-agnostic.
 
     Produced by the adapter's parse_event() method.
+
+    ``distribution`` is the host-declared :class:`HostDistribution` (the host's
+    own channel and, when applicable, its distribution root). It replaces the
+    former ``channel`` / ``plugin_root`` pair so the core never enumerates a
+    host's distribution channels. It is ``None`` when the adapter does not
+    declare a distribution model for the event.
     """
 
     event_type: HookEventType
     session_id: str
     payload: Dict[str, Any]
-    channel: DistributionChannel
-    plugin_root: Optional[Path] = None
+    distribution: Optional[HostDistribution] = None
 
 
 @dataclass(frozen=True)
@@ -105,6 +169,70 @@ class ValidationResult:
     nonce: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class ConsentRequest:
+    """CLI-agnostic description of an operation that needs the user's consent.
+
+    Business logic produces this when it has classified an operation as
+    requiring approval (a T3 mutation, a protected-path write). It states only
+    the *facts* of what needs consent -- never how to ask. The adapter's
+    :meth:`HookAdapter.request_consent` turns it into the host's consent
+    mechanism (a native permission prompt, an approval-id hand-off, ...), so the
+    core never names the host's specific consent flow.
+
+    Fields:
+        operation: The thing needing consent -- a shell command, or a file path.
+        kind: Coarse classification of ``operation`` ("bash", "file", ...).
+            Lets the adapter tailor the prompt wording without parsing.
+        reason: Human-readable explanation of why consent is required, already
+            assembled by business logic (tier banner, verb, command excerpt).
+        tier: The security tier string (e.g. "T3_BLOCKED"); informational.
+        approval_id: When the host runs an out-of-band approval flow (an
+            orchestrator driving the approval cycle), this is the persisted
+            identifier the user's decision is keyed to. None means the host
+            should gather consent inline (e.g. a native prompt).
+        updated_input: Optional modified tool input (e.g. footer-stripped
+            command) the host must preserve through the consent step.
+    """
+
+    operation: str
+    kind: str = "bash"
+    reason: str = ""
+    tier: str = "T3_BLOCKED"
+    approval_id: Optional[str] = None
+    updated_input: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class CapabilityDegradation:
+    """The DECLARED outcome of querying a host for a capability.
+
+    Returned by :meth:`HookAdapter.degrade_when_missing`. It is the explicit,
+    observable answer to "does this host offer capability X, and if not, what
+    safe thing happens instead?" -- the controlled alternative to a crash or an
+    implicit ``if host == "claude_code"`` branch. Business logic receives this
+    value, reads :attr:`available`, and follows :attr:`fallback` when the
+    capability is absent. Nothing here knows which host produced it.
+
+    Fields:
+        capability: The :class:`HostCapability` that was queried.
+        available: True when the host declared support for ``capability``.
+            When True, ``fallback`` is the empty string and ``reason`` is
+            informational only -- the caller uses the full capability.
+        fallback: The semantic name of the safe behavior to take when the
+            capability is NOT available (e.g. "deny", "skip", "log_only").
+            Chosen by the caller and echoed back so the degradation is a
+            value the caller declared, not a side effect it must remember.
+        reason: Human-readable explanation of the degradation, suitable for
+            surfacing in a log or a denial message.
+    """
+
+    capability: HostCapability
+    available: bool
+    fallback: str = ""
+    reason: str = ""
+
+
 @dataclass(frozen=True)
 class ToolResult:
     """Post-tool-use result data extracted from a HookEvent."""

package/dist/gaia-ops/hooks/modules/agents/transcript_reader.py

@@ -10,57 +10,39 @@ Provides:
 
 import json
 import logging
+import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from adapters.host_transcript import iter_transcript_entries
+
 logger = logging.getLogger(__name__)
 
 
 def read_transcript(transcript_path: str) -> str:
-    """Read agent transcript from file path provided by Claude Code.
+    """Read assistant messages from the host transcript provided by the CLI.
 
-    Claude Code provides ``agent_transcript_path`` pointing to a JSONL file.
-    Each line has the structure:
-        {"type": "assistant", "message": {"role": "assistant", "content": [...]}, ...}
-    The role/content are nested inside the ``message`` field.
+    The host CLI advertises ``agent_transcript_path``; the on-disk format
+    (JSONL, ``message``-nesting) is owned by ``adapters/host_transcript.py``.
+    This reader iterates normalized ``(role, content)`` entries from that
+    adapter and joins the text of every ``assistant`` message -- it makes no
+    assumption about how the host serializes the transcript.
 
     Falls back to empty string on any error so the hook never crashes.
     """
     try:
-        # Expand ~ to home directory (Claude Code may use ~ in paths)
-        path = Path(transcript_path).expanduser()
-        logger.debug("Reading transcript from: %s", path)
-
-        if not path.exists():
-            logger.warning("Transcript file not found: %s", path)
-            return ""
-
-        lines = path.read_text().strip().splitlines()
-
         text_parts: List[str] = []
-        for line in lines:
-            if not line.strip():
-                continue
-            try:
-                entry = json.loads(line)
-
-                # Claude Code transcript format: content is inside entry["message"]
-                msg = entry.get("message", entry)  # fallback to entry itself for simple format
-                role = msg.get("role", "")
-                if role != "assistant":
-                    continue
-
-                content = msg.get("content", "")
-                if isinstance(content, str):
-                    text_parts.append(content)
-                elif isinstance(content, list):
-                    for block in content:
-                        if isinstance(block, dict) and block.get("type") == "text":
-                            text_parts.append(block.get("text", ""))
-                        elif isinstance(block, str):
-                            text_parts.append(block)
-            except (json.JSONDecodeError, TypeError):
+        for role, content in iter_transcript_entries(transcript_path):
+            if role != "assistant":
                 continue
+            if isinstance(content, str):
+                text_parts.append(content)
+            elif isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "text":
+                        text_parts.append(block.get("text", ""))
+                    elif isinstance(block, str):
+                        text_parts.append(block)
 
         result = "\n".join(text_parts)
         logger.debug("Extracted %d text parts, total length: %d chars", len(text_parts), len(result))
@@ -72,41 +54,24 @@ def read_transcript(transcript_path: str) -> str:
 
 
 def read_first_user_content_from_transcript(transcript_path: str) -> Optional[str]:
-    """Read the raw content string of the first user message from a transcript JSONL.
+    """Read the raw content of the first user message from the host transcript.
 
-    Handles: empty path guard, path expansion, existence check, JSONL iteration,
-    JSON parse, role=="user" check, content normalization (str vs list).
-    Returns the raw content string or None.
+    Iterates normalized ``(role, content)`` entries from the adapter (which
+    owns the host transcript format) and returns the content of the first
+    ``user`` message, normalized to a string. Returns None when there is no
+    user message (or the path is empty/missing).
     """
-    if not transcript_path:
+    for role, content in iter_transcript_entries(transcript_path):
+        if role != "user":
+            continue
+        if isinstance(content, str):
+            return content
+        elif isinstance(content, list):
+            return " ".join(
+                b.get("text", "") for b in content
+                if isinstance(b, dict) and b.get("type") == "text"
+            )
         return None
-    try:
-        path = Path(transcript_path).expanduser()
-        if not path.exists():
-            return None
-        with open(path, "r") as f:
-            for line in f:
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    entry = json.loads(line)
-                    msg = entry.get("message", entry)
-                    if msg.get("role") != "user":
-                        continue
-                    content = msg.get("content", "")
-                    if isinstance(content, str):
-                        return content
-                    elif isinstance(content, list):
-                        return " ".join(
-                            b.get("text", "") for b in content
-                            if isinstance(b, dict) and b.get("type") == "text"
-                        )
-                    return None
-                except (json.JSONDecodeError, TypeError):
-                    continue
-    except Exception as e:
-        logger.debug("Failed to read first user content from transcript: %s", e)
     return None
 
 
@@ -137,8 +102,6 @@ def extract_injected_context_payload_from_transcript(
     Context is delivered via additionalContext and the payload is persisted to
     disk by context_injector. Prompts do not contain embedded payloads.
     """
-    import os
-
     # Empty/None path guard. Without it, Path("").stem == "" and the substring
     # match below (``candidate.stem in "" or "" in candidate.stem``) is ALWAYS
     # True because ``"" in any_string`` is True -- so an empty path would match

package/dist/gaia-ops/hooks/modules/core/hook_entry.py

@@ -38,7 +38,7 @@ def run_hook(
     hook_name: str = "hook",
     usage_message: str | None = None,
 ) -> None:
-    """Read stdin, parse via ClaudeCodeAdapter, and delegate to *handler*.
+    """Read stdin, parse via the registry adapter, and delegate to *handler*.
 
     Args:
         handler: Callable that receives an ``adapters.types.HookEvent``.
@@ -58,10 +58,12 @@ def run_hook(
 
     try:
         # Deferred adapter import avoids circular dependencies at module level;
-        # the adapter package is a sibling of modules/.
-        from adapters.claude_code import ClaudeCodeAdapter
+        # the adapter package is a sibling of modules/. get_adapter() is the
+        # single construction point (registry), so entry points never name the
+        # concrete host class.
+        from adapters.registry import get_adapter
 
-        adapter = ClaudeCodeAdapter()
+        adapter = get_adapter()
         stdin_data = sys.stdin.read()
         event = adapter.parse_event(stdin_data)
         handler(event)

package/dist/gaia-ops/hooks/modules/core/state.py

@@ -5,7 +5,6 @@ Uses a temporary file to pass information from pre_tool_use to post_tool_use,
 since they run in separate processes.
 """
 
-import os
 import json
 import logging
 import time
@@ -14,6 +13,8 @@ from datetime import datetime
 from typing import Dict, Any, Optional
 from dataclasses import dataclass, asdict, field
 
+from adapters.host_session import read_host_session_id
+
 from .paths import find_claude_dir
 
 logger = logging.getLogger(__name__)
@@ -23,15 +24,16 @@ STATE_FILE_NAME = ".hooks_state.json"
 
 
 def get_session_id() -> str:
-    """Return the current Claude session ID, defaulting to 'default'.
+    """Return the current host session ID, defaulting to 'default'.
 
-    Reads only CLAUDE_SESSION_ID. Hook entry points that have the parsed
+    Reads only the host session environment variable (via the adapter-owned
+    ``read_host_session_id`` helper). Hook entry points that have the parsed
     stdin event in hand should prefer ``resolve_session_id(event_data)``
-    because Claude Code does not always set CLAUDE_SESSION_ID in the hook
-    subprocess; it does, however, always include ``session_id`` in the
+    because the host CLI does not always export the session env var into the
+    hook subprocess; it does, however, always include ``session_id`` in the
     JSON event piped to stdin.
     """
-    return os.environ.get("CLAUDE_SESSION_ID", "default")
+    return read_host_session_id()
 
 
 def resolve_session_id(event_data: Optional[Dict[str, Any]] = None) -> str:
@@ -39,20 +41,20 @@ def resolve_session_id(event_data: Optional[Dict[str, Any]] = None) -> str:
 
     Order:
       1. ``event_data["session_id"]`` when present and non-empty.
-      2. ``CLAUDE_SESSION_ID`` environment variable.
+      2. The host session environment variable (via the adapter helper).
       3. Literal ``"default"`` (matches ``get_session_id()`` for back-compat).
 
     Hook entry points should call this immediately after parsing stdin so
     downstream calls (``register_session``, ``touch_session``,
-    ``unregister_session``) reach the registry with the real id.
-    ``CLAUDE_SESSION_ID`` is not guaranteed to be exported into the hook
+    ``unregister_session``) reach the registry with the real id. The host
+    session env var is not guaranteed to be exported into the hook
     subprocess; the stdin event always carries ``session_id``.
     """
     if isinstance(event_data, dict):
         candidate = event_data.get("session_id")
         if isinstance(candidate, str) and candidate:
             return candidate
-    return os.environ.get("CLAUDE_SESSION_ID", "default")
+    return read_host_session_id()
 
 
 @dataclass

package/dist/gaia-ops/hooks/modules/security/approval_cleanup.py

@@ -219,8 +219,8 @@ def cleanup(
 
     Args:
         agent_type: The agent type that just completed (provenance + logging).
-        session_id: Session ID to scope the TTL sweep (defaults to
-            CLAUDE_SESSION_ID).
+        session_id: Session ID to scope the TTL sweep (defaults to the
+            current host session id).
         preserve_nonces: Optional set of approval_id strings the agent's final
             agent_contract_handoff still references via APPROVAL_REQUEST. With
             Fix A these are protected by their TTL already (they are fresh by

package/dist/gaia-ops/hooks/modules/security/approval_grants.py

@@ -887,7 +887,7 @@ def write_pending_approval_for_file(
         nonce: Cryptographic nonce from generate_nonce().  The DB row is stored
             under approval_id = "P-" + nonce.
         file_path: The absolute path of the file being written/edited.
-        session_id: Session ID (defaults to CLAUDE_SESSION_ID env var).
+        session_id: Session ID (defaults to the current host session id).
         ttl_minutes: How long the pending approval is valid before expiry
             (0 = no expiry; ignored by DB which uses TTL at query time).
         context: Optional dict with enriched context (source, description,
@@ -1015,8 +1015,8 @@ def find_pending_for_file(
         return None
 
     # DB path: query all pending rows (all_sessions=True -- see scan_pending_db
-    # for the rationale: CLAUDE_SESSION_ID inside a subagent is the subagent's id,
-    # not the orchestrator's, so session-scoping would silently miss the row).
+    # for the rationale: the host session id inside a subagent is the subagent's
+    # id, not the orchestrator's, so session-scoping would silently miss the row).
     try:
         from gaia.approvals.store import list_pending
         rows = list_pending(all_sessions=True)
@@ -1564,7 +1564,7 @@ def create_command_set_grant(
     Args:
         command_set: List of dicts [{"command": str, "rationale": str}, ...].
         approval_id: Unique nonce (32-char hex from generate_nonce()).
-        session_id: CLAUDE_SESSION_ID (defaults to current session).
+        session_id: Host session id (defaults to current session).
         agent_id: Agent identifier for audit trail.
         ttl_minutes: Grant lifetime (default 10 min). Enforced at query time.
         db_path: Optional explicit DB path override (used by tests).
@@ -1634,9 +1634,9 @@ def match_command_set_grant(
 
     The lookup is SESSION-AGNOSTIC (Brief 71), exactly like the singular path
     (``check_db_semantic_grant``). The block-approve-retry flow legitimately
-    spans sessions, and CLAUDE_SESSION_ID is not guaranteed to be exported into
-    the bash subprocess -- where ``get_session_id()`` falls back to the literal
-    ``"default"``. A session_id filter therefore silently dropped every grant
+    spans sessions, and the host session id is not guaranteed to be exported
+    into the bash subprocess -- where ``get_session_id()`` falls back to the
+    literal ``"default"``. A session_id filter therefore silently dropped every grant
     created under the real session, letting approved COMMAND_SET commands run
     WITHOUT being consumed (the consumption-bypass bug). Replay protection is
     preserved by the conjunction of the byte-for-byte match, status='PENDING'