@jaguilar87/gaia 5.0.9 → 5.0.11

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

@@ -9,15 +9,19 @@ they never see raw CLI JSON.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from typing import FrozenSet
 
 from .types import (
     AgentCompletion,
     BootstrapResult,
+    CapabilityDegradation,
     CompletionResult,
+    ConsentRequest,
     ContextResult,
-    DistributionChannel,
     HookEvent,
     HookResponse,
+    HostCapability,
+    HostDistribution,
     QualityResult,
     ValidationResult,
     VerificationResult,
@@ -68,6 +72,105 @@ class HookAdapter(ABC):
         """
         ...
 
+    @abstractmethod
+    def request_consent(self, request: ConsentRequest) -> HookResponse:
+        """Ask the user to consent to an operation, via the host's mechanism.
+
+        The single entry point through which business logic requests user
+        consent for an operation it has classified as approval-requiring (a T3
+        mutation, a protected-path write). Business logic hands over the
+        CLI-agnostic facts (:class:`ConsentRequest`) and never names how the
+        host gathers consent: the concrete adapter owns that mechanism entirely
+        (a native permission prompt, an out-of-band approval-id hand-off, ...).
+        Adding or changing the host's consent flow is a change to this method
+        alone -- the core's tier classification, grants, and validation stay
+        untouched.
+
+        Preconditions:
+            - request.operation is a non-empty string
+            - request.reason is the human-readable explanation to surface
+
+        Postconditions:
+            - Returns a HookResponse that drives the host to obtain consent
+              (it does not silently allow or permanently block)
+            - When request.approval_id is set, the response keys the user's
+              decision to that identifier; when None, the host gathers consent
+              inline
+            - When request.updated_input is set, the response preserves it
+              through the consent step
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # Host capabilities: declaration + agnostic query + declared degradation
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def capabilities(self) -> FrozenSet[HostCapability]:
+        """DECLARE which host capabilities this adapter supports.
+
+        The single place a host states what it can do. Each concrete adapter
+        returns the exact set of :class:`HostCapability` members its host
+        offers -- nothing inferred, nothing implicit. Business logic never
+        reads this set directly; it asks through :meth:`supports` /
+        :meth:`degrade_when_missing`, which are host-agnostic.
+
+        Adding a host (Codex, Antigravity) that lacks a capability is a change
+        to this declaration alone: the core's query and degradation logic stay
+        untouched, and the absence drives the declared degradation path.
+
+        Postconditions:
+            - Returns a frozenset of HostCapability members (possibly empty).
+            - The result is stable for the lifetime of the adapter instance.
+        """
+        ...
+
+    def supports(self, capability: HostCapability) -> bool:
+        """Ask, host-agnostically, whether ``capability`` is available.
+
+        A concrete query over :meth:`capabilities` so business logic can branch
+        on *what the host can do* rather than *which host it is*. Defined here
+        (not abstract) so every adapter shares one query semantics; only the
+        underlying declaration differs.
+        """
+        return capability in self.capabilities()
+
+    def degrade_when_missing(
+        self,
+        capability: HostCapability,
+        fallback: str,
+        reason: str = "",
+    ) -> CapabilityDegradation:
+        """Return the DECLARED degradation for ``capability`` on this host.
+
+        The host-agnostic entry point for safe degradation. Business logic that
+        needs an optional capability calls this with the ``fallback`` it will
+        take if the capability is absent and an optional ``reason``. The result
+        is an explicit, observable :class:`CapabilityDegradation`:
+
+        - capability present -> ``available=True``, ``fallback=""`` (use it).
+        - capability absent  -> ``available=False`` carrying the caller's
+          ``fallback`` and a ``reason`` (degrade in the declared, safe way).
+
+        This replaces the two failure modes the brief forbids: a crash when a
+        host lacks a capability, and an implicit ``if host == ...`` branch. The
+        degradation is a value, returned the same way for every host.
+        """
+        if self.supports(capability):
+            return CapabilityDegradation(
+                capability=capability,
+                available=True,
+                fallback="",
+                reason=reason,
+            )
+        return CapabilityDegradation(
+            capability=capability,
+            available=False,
+            fallback=fallback,
+            reason=reason
+            or f"host does not support {capability.value}; degrading to '{fallback}'",
+        )
+
     @abstractmethod
     def format_completion_response(self, result: CompletionResult) -> HookResponse:
         """Format a CompletionResult for CLI consumption.
@@ -159,11 +262,25 @@ class HookAdapter(ABC):
         ...
 
     @abstractmethod
-    def detect_channel(self) -> DistributionChannel:
-        """Detect the distribution channel (NPM or PLUGIN).
+    def detect_distribution(self) -> HostDistribution:
+        """DECLARE the host's distribution model for the current invocation.
 
-        Checks environment variables and filesystem layout to determine
-        how gaia-ops was installed.
+        The single place a host states HOW it distributes and invokes gaia-ops:
+        its own channel identifier and, when it has one, the distribution root.
+        The core never enumerates a host's channels nor reads a host-specific
+        env var to learn them -- it receives an opaque :class:`HostDistribution`
+        and carries it on the :class:`HookEvent`.
+
+        Adding a host with a different distribution model (a native extension
+        with its own root, a single canonical channel, ...) is a change to this
+        method alone: the concrete adapter declares its own channel names and
+        root resolution, and the core vocabulary stays untouched -- the same
+        seam used for :meth:`capabilities` and :meth:`request_consent`.
+
+        Postconditions:
+            - Returns a HostDistribution whose ``channel`` is the host's own
+              channel identifier and whose ``root`` is the distribution root
+              for that channel, or None when the channel has no root.
         """
         ...
 

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

@@ -18,18 +18,20 @@ import os
 import re
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, FrozenSet, List, Optional
 
 from .base import HookAdapter
 from .types import (
     AgentCompletion,
     BootstrapResult,
     CompletionResult,
+    ConsentRequest,
     ContextResult,
-    DistributionChannel,
     HookEvent,
     HookEventType,
     HookResponse,
+    HostCapability,
+    HostDistribution,
     PermissionDecision,
     QualityResult,
     ToolResult,
@@ -40,6 +42,58 @@ from .types import (
 
 logger = logging.getLogger(__name__)
 
+# Claude Code's PreToolUse responses nest their permission fields under this
+# top-level key. The literal shape is OWNED by this adapter layer: business
+# logic must never index it directly. The accessors below let business modules
+# read or augment an already-formatted host response without coupling to the
+# key names (AC-2: hookSpecificOutput lives only in adapters/).
+_HOOK_SPECIFIC_OUTPUT = "hookSpecificOutput"
+
+# Claude Code's two distribution channels and the env var that distinguishes
+# them. These host-specific names are OWNED by this adapter (Gap 2 / brief #88):
+# the core carries an opaque HostDistribution and never enumerates these values
+# nor reads CLAUDE_PLUGIN_ROOT. A host with a different distribution model
+# declares its own channels in its own adapter, with no change to the core.
+_CHANNEL_NPM = "npm"
+_CHANNEL_PLUGIN = "plugin"
+_PLUGIN_ROOT_ENV_VAR = "CLAUDE_PLUGIN_ROOT"
+
+
+def read_permission_decision(host_output: Dict[str, Any]) -> Optional[str]:
+    """Return the permissionDecision ("allow"/"deny"/"ask") from a host response.
+
+    Reads the Claude Code ``hookSpecificOutput`` shape produced by this adapter.
+    Returns None when the response is not a permission-decision response.
+    """
+    if not isinstance(host_output, dict):
+        return None
+    return host_output.get(_HOOK_SPECIFIC_OUTPUT, {}).get("permissionDecision")
+
+
+def read_permission_reason(host_output: Dict[str, Any]) -> str:
+    """Return the permissionDecisionReason from a host response, or "" if absent."""
+    if not isinstance(host_output, dict):
+        return ""
+    return host_output.get(_HOOK_SPECIFIC_OUTPUT, {}).get(
+        "permissionDecisionReason", ""
+    )
+
+
+def inject_updated_input(
+    host_output: Dict[str, Any], updated_input: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Attach ``updatedInput`` to an already-formatted host response, in place.
+
+    Used when business logic must propagate a modified tool input (e.g. a
+    footer-stripped command) through an existing block/ask response so the
+    modification survives the native permission dialog. Returns the same dict
+    for convenience. No-op when ``host_output`` is not a host response.
+    """
+    if not isinstance(host_output, dict):
+        return host_output
+    host_output.setdefault(_HOOK_SPECIFIC_OUTPUT, {})["updatedInput"] = updated_input
+    return host_output
+
 
 def _append_workspace_memory(context: str) -> str:
     """Append the curated workspace memory block to a subagent context string.
@@ -115,15 +169,11 @@ class ClaudeCodeAdapter(HookAdapter):
 
         session_id = raw.get("session_id", "")
 
-        channel = self.detect_channel()
-        plugin_root = self._get_plugin_root() if channel == DistributionChannel.PLUGIN else None
-
         return HookEvent(
             event_type=event_type,
             session_id=session_id,
             payload=raw,
-            channel=channel,
-            plugin_root=plugin_root,
+            distribution=self.detect_distribution(),
         )
 
     # ------------------------------------------------------------------ #
@@ -268,19 +318,53 @@ class ClaudeCodeAdapter(HookAdapter):
         return HookResponse(output=output, exit_code=0)
 
     # ------------------------------------------------------------------ #
-    # detect_channel: determine NPM vs PLUGIN distribution
+    # detect_distribution: declare the host's channel + root (NPM vs PLUGIN)
     # ------------------------------------------------------------------ #
 
-    def detect_channel(self) -> DistributionChannel:
-        """Detect distribution channel.
+    # ------------------------------------------------------------------ #
+    # capabilities: Claude Code DECLARES what this host can do
+    # ------------------------------------------------------------------ #
+
+    # Frozen, instance-stable declaration. Claude Code v2.1+ offers every
+    # capability the core currently asks about: it gathers consent inline via
+    # AskUserQuestion (INTERACTIVE_CONSENT), runs the orchestrator approval-id
+    # cycle (OUT_OF_BAND_APPROVAL), accepts a structured permissionDecision
+    # (STRUCTURED_PERMISSION_DECISION), applies updatedInput transparently
+    # (UPDATED_INPUT), injects SessionStart/SubagentStart context
+    # (CONTEXT_INJECTION), and exposes the agent transcript (TRANSCRIPT_ACCESS).
+    # A future host that lacks one simply omits it here; the absence drives the
+    # core's declared degradation, with no change to business logic.
+    _CAPABILITIES: FrozenSet[HostCapability] = frozenset(
+        {
+            HostCapability.INTERACTIVE_CONSENT,
+            HostCapability.OUT_OF_BAND_APPROVAL,
+            HostCapability.STRUCTURED_PERMISSION_DECISION,
+            HostCapability.UPDATED_INPUT,
+            HostCapability.CONTEXT_INJECTION,
+            HostCapability.TRANSCRIPT_ACCESS,
+        }
+    )
+
+    def capabilities(self) -> FrozenSet[HostCapability]:
+        """Declare the capabilities Claude Code offers (see ``_CAPABILITIES``)."""
+        return self._CAPABILITIES
+
+    def detect_distribution(self) -> HostDistribution:
+        """Declare Claude Code's distribution model for this invocation.
+
+        Resolves Claude Code's two channels and their root, then hands the core
+        an opaque :class:`HostDistribution`:
+
+        1. CLAUDE_PLUGIN_ROOT env var set -> "plugin" channel, root = that path
+        2. Default                        -> "npm" channel, no root
 
-        Priority:
-        1. CLAUDE_PLUGIN_ROOT env var set -> PLUGIN
-        2. Default -> NPM
+        The channel names and the env var are confined to this adapter; the core
+        never sees them.
         """
-        if os.environ.get("CLAUDE_PLUGIN_ROOT"):
-            return DistributionChannel.PLUGIN
-        return DistributionChannel.NPM
+        plugin_root = self._get_plugin_root()
+        if plugin_root is not None:
+            return HostDistribution(channel=_CHANNEL_PLUGIN, root=plugin_root)
+        return HostDistribution(channel=_CHANNEL_NPM, root=None)
 
     # ------------------------------------------------------------------ #
     # Helper: get_plugin_root
@@ -288,7 +372,7 @@ class ClaudeCodeAdapter(HookAdapter):
 
     def _get_plugin_root(self) -> Optional[Path]:
         """Resolve plugin root from CLAUDE_PLUGIN_ROOT env var."""
-        plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+        plugin_root = os.environ.get(_PLUGIN_ROOT_ENV_VAR)
         if plugin_root:
             return Path(plugin_root)
         return None
@@ -446,6 +530,47 @@ class ClaudeCodeAdapter(HookAdapter):
             output["hookSpecificOutput"]["updatedInput"] = updated_input
         return HookResponse(output=output, exit_code=0)
 
+    # ------------------------------------------------------------------ #
+    # request_consent: host-specific consent mechanism (AskUserQuestion /
+    # orchestrator approval-id hand-off) -- the ONLY place either lives.
+    # ------------------------------------------------------------------ #
+
+    def request_consent(self, request: ConsentRequest) -> HookResponse:
+        """Drive Claude Code to obtain the user's consent for ``request``.
+
+        This is where Claude Code's consent mechanics live and nowhere else.
+        Two host shapes, selected by whether an out-of-band approval flow owns
+        the decision:
+
+        - ``approval_id`` set -> the orchestrator drives the Gaia approval
+          cycle. Emit a ``deny`` keyed to that ``approval_id``; the subagent
+          reports APPROVAL_REQUEST, the user clicks Approve in the native
+          AskUserQuestion prompt, and the ElicitationResult hook activates the
+          grant. The ``reason`` already carries the approval_id banner, so this
+          is a thin formatting step.
+        - ``approval_id`` is None -> gather consent inline via Claude Code's
+          native permission prompt (``permissionDecision: "ask"`` ->
+          AskUserQuestion), preserving ``updated_input`` through the dialog.
+
+        Business logic calls this without knowing either shape exists.
+        """
+        if request.approval_id is not None:
+            # Out-of-band approval flow: deny now, decision keyed to approval_id.
+            return HookResponse(
+                output={
+                    _HOOK_SPECIFIC_OUTPUT: {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": PermissionDecision.DENY.value,
+                        "permissionDecisionReason": request.reason,
+                    }
+                },
+                exit_code=0,
+            )
+        # Inline consent via the native AskUserQuestion permission prompt.
+        return self.format_ask_response(
+            request.reason, updated_input=request.updated_input
+        )
+
     # ------------------------------------------------------------------ #
     # adapt_pre_tool_use: full pre-tool-use lifecycle
     # ------------------------------------------------------------------ #
@@ -587,14 +712,14 @@ class ClaudeCodeAdapter(HookAdapter):
                     return HookResponse(output=output, exit_code=2)
                 # Mutative commands (git commit, terraform apply, etc.) → ask user
                 logger.info("SECURITY MODE: returning 'ask' for T3: %s", command[:80])
-                output = {
-                    "hookSpecificOutput": {
-                        "hookEventName": "PreToolUse",
-                        "permissionDecision": "ask",
-                        "permissionDecisionReason": f"[{result.tier}] {reason_line}",
-                    }
-                }
-                return HookResponse(output=output, exit_code=0)
+                return self.request_consent(
+                    ConsentRequest(
+                        operation=command,
+                        kind="bash",
+                        reason=f"[{result.tier}] {reason_line}",
+                        tier=str(result.tier),
+                    )
+                )
             # Ops mode: block with nonce for orchestrator approval flow
             if result.block_response is not None:
                 return HookResponse(output=result.block_response, exit_code=0)
@@ -848,20 +973,19 @@ class ClaudeCodeAdapter(HookAdapter):
         )
 
         if not is_subagent:
-            # Foreground / orchestrator context: use native approval dialog.
+            # Foreground / orchestrator context: ask the user for consent
+            # inline (the adapter maps this to the native approval dialog).
             reason = (
                 "[PROTECTED_PATH] Modifications to Gaia hooks and security config "
                 "require approval."
             )
-            return HookResponse(
-                output={
-                    "hookSpecificOutput": {
-                        "hookEventName": "PreToolUse",
-                        "permissionDecision": "ask",
-                        "permissionDecisionReason": reason,
-                    }
-                },
-                exit_code=0,
+            return self.request_consent(
+                ConsentRequest(
+                    operation=file_path,
+                    kind="file",
+                    reason=reason,
+                    tier="T3_BLOCKED",
+                )
             )
 
         # Subagent context: nonce-based pending approval flow.
@@ -905,15 +1029,13 @@ class ClaudeCodeAdapter(HookAdapter):
                     "require approval. (Pending approval persistence failed; "
                     "native dialog fallback.)"
                 )
-                return HookResponse(
-                    output={
-                        "hookSpecificOutput": {
-                            "hookEventName": "PreToolUse",
-                            "permissionDecision": "ask",
-                            "permissionDecisionReason": reason,
-                        }
-                    },
-                    exit_code=0,
+                return self.request_consent(
+                    ConsentRequest(
+                        operation=file_path,
+                        kind="file",
+                        reason=reason,
+                        tier="T3_BLOCKED",
+                    )
                 )
 
         reason = (
@@ -924,15 +1046,15 @@ class ClaudeCodeAdapter(HookAdapter):
             f"Tool: {tool_name}\n"
             f"approval_id: {approval_id}"
         )
-        return HookResponse(
-            output={
-                "hookSpecificOutput": {
-                    "hookEventName": "PreToolUse",
-                    "permissionDecision": "deny",
-                    "permissionDecisionReason": reason,
-                }
-            },
-            exit_code=0,
+        # Out-of-band approval flow: consent is keyed to the persisted approval_id.
+        return self.request_consent(
+            ConsentRequest(
+                operation=file_path,
+                kind="file",
+                reason=reason,
+                tier="T3_BLOCKED",
+                approval_id=approval_id,
+            )
         )
 
     @staticmethod

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