@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/hooks/adapters/claude_code.py

@@ -18,7 +18,7 @@ import os
 import re
 import time
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from .base import HookAdapter
 from .types import (
@@ -49,7 +49,7 @@ class ClaudeCodeAdapter(HookAdapter):
         - session_id: str
         - tool_name: str        (PreToolUse / PostToolUse)
         - tool_input: dict      (PreToolUse / PostToolUse)
-        - tool_result: dict     (PostToolUse only)
+        - tool_response: dict    (PostToolUse only)
         - agent_type: str       (SubagentStop only)
         - agent_id: str         (SubagentStop only)
         - agent_transcript_path: str  (SubagentStop only)
@@ -177,16 +177,23 @@ class ClaudeCodeAdapter(HookAdapter):
     # ------------------------------------------------------------------ #
 
     def format_context_response(self, result: ContextResult) -> HookResponse:
-        """Format a ContextResult for context injection hooks.
+        """Format a ContextResult for SubagentStart context injection.
 
-        Returns additionalContext field that Claude Code appends to the prompt.
-        Note: UserPromptSubmit was simplified to a static echo in settings.json.
-        This method is retained for SubagentStart and future context injection hooks.
+        Claude Code expects SubagentStart hooks to return::
+
+            {"hookSpecificOutput": {"hookEventName": "SubagentStart",
+                                    "additionalContext": "..."}}
+
+        The additionalContext string is appended to the subagent's system prompt.
         """
-        output: Dict[str, Any] = {}
+        hook_specific: Dict[str, Any] = {
+            "hookEventName": "SubagentStart",
+        }
 
         if result.context_injected and result.additional_context:
-            output["additionalContext"] = result.additional_context
+            hook_specific["additionalContext"] = result.additional_context
+
+        output: Dict[str, Any] = {"hookSpecificOutput": hook_specific}
 
         if result.sections_provided:
             output["sections_provided"] = result.sections_provided
@@ -324,12 +331,12 @@ class ClaudeCodeAdapter(HookAdapter):
         """
         tool_name = raw.get("tool_name", "")
         tool_input = raw.get("tool_input", {})
-        tool_result = raw.get("tool_result", {})
+        tool_response = raw.get("tool_response", {})
         session_id = raw.get("session_id", "")
 
         command = tool_input.get("command", "")
-        output = tool_result.get("output", "")
-        exit_code = tool_result.get("exit_code", 0)
+        output = tool_response.get("output", "")
+        exit_code = tool_response.get("exit_code", 0)
 
         return ToolResult(
             tool_name=tool_name,
@@ -407,24 +414,11 @@ class ClaudeCodeAdapter(HookAdapter):
         context injection, approval handling, and response formatting.
         """
         from modules.core.state import create_pre_hook_state, save_hook_state
-        from modules.security.approval_constants import (
-            NONCE_APPROVAL_PATTERN,
-        )
-        from modules.security.approval_messages import (
-            build_activation_failed_message,
-            build_deprecated_approval_message,
-            build_invalid_nonce_message,
-        )
         from modules.security.approval_grants import (
-            activate_pending_approval,
             cleanup_expired_grants,
         )
         from modules.tools.bash_validator import BashValidator
         from modules.tools.task_validator import TaskValidator, AVAILABLE_AGENTS, META_AGENTS
-        from modules.security.prompt_validator import classify_resume_prompt
-        from modules.context.context_injector import inject_project_context
-        from modules.session.session_event_injector import inject_session_events
-
         hook_data = event.payload
         tool_name = hook_data.get("tool_name") or ""
         tool_input = hook_data.get("tool_input", {})
@@ -432,6 +426,28 @@ class ClaudeCodeAdapter(HookAdapter):
         logger.info("Hook invoked: tool=%s, params=%s", tool_name, json.dumps(tool_input)[:200])
 
         try:
+            # ── Delegate mode gate ─────────────────────────────────
+            # Must run before any other logic.  When enabled, the
+            # orchestrator (main session) is restricted to dispatch-only
+            # tools.  Subagents are unaffected.
+            from modules.orchestrator.delegate_mode import check_delegate_mode
+
+            dm_result = check_delegate_mode(tool_name, hook_data)
+            if dm_result.blocked:
+                logger.warning(
+                    "DELEGATE_MODE denied %s for orchestrator", tool_name,
+                )
+                return HookResponse(
+                    output={
+                        "hookSpecificOutput": {
+                            "hookEventName": "PreToolUse",
+                            "permissionDecision": "deny",
+                            "permissionDecisionReason": dm_result.reason,
+                        }
+                    },
+                    exit_code=0,
+                )
+
             # Periodic cleanup of expired approval grants
             cleanup_expired_grants()
 
@@ -441,12 +457,13 @@ class ClaudeCodeAdapter(HookAdapter):
                 return HookResponse(output="Error: Invalid parameters", exit_code=2)
 
             if tool_name.lower() == "bash":
-                return self._adapt_bash(tool_name, tool_input)
+                return self._adapt_bash(tool_name, tool_input, hook_data=hook_data)
             elif tool_name.lower() in ("task", "agent"):
                 hooks_dir = Path(__file__).parent.parent
                 project_agents = [a for a in AVAILABLE_AGENTS if a not in META_AGENTS]
                 return self._adapt_task(
                     tool_name, tool_input, project_agents, hooks_dir,
+                    session_id=event.session_id,
                 )
             elif tool_name.lower() == "sendmessage":
                 return self._adapt_send_message(tool_name, tool_input)
@@ -461,8 +478,20 @@ class ClaudeCodeAdapter(HookAdapter):
                 exit_code=2,
             )
 
-    def _adapt_bash(self, tool_name: str, parameters: dict) -> HookResponse:
-        """Handle Bash tool validation within the adapter."""
+    def _adapt_bash(
+        self,
+        tool_name: str,
+        parameters: dict,
+        hook_data: dict | None = None,
+    ) -> HookResponse:
+        """Handle Bash tool validation within the adapter.
+
+        Args:
+            tool_name: The tool name ("Bash").
+            parameters: The tool_input dict (contains "command").
+            hook_data: Full hook event payload -- used to detect subagent
+                context via the ``agent_id`` field.
+        """
         from modules.core.state import create_pre_hook_state, save_hook_state
         from modules.tools.bash_validator import BashValidator
 
@@ -470,8 +499,15 @@ class ClaudeCodeAdapter(HookAdapter):
         if not command:
             return HookResponse(output="Error: Bash tool requires a command", exit_code=2)
 
+        # Detect subagent context: if agent_id is present in the hook event,
+        # the command is running inside a subagent (not the orchestrator).
+        is_subagent = bool(hook_data and hook_data.get("agent_id"))
+        session_id = (hook_data or {}).get("session_id", "")
+
         validator = BashValidator()
-        result = validator.validate(command)
+        result = validator.validate(
+            command, is_subagent=is_subagent, session_id=session_id,
+        )
 
         if not result.allowed:
             from modules.core.plugin_mode import is_ops_mode
@@ -542,11 +578,13 @@ class ClaudeCodeAdapter(HookAdapter):
         parameters: dict,
         project_agents: list,
         hooks_dir: Path,
+        session_id: str = "",
     ) -> HookResponse:
         """Handle Task/Agent tool validation within the adapter.
 
-        Uses additionalContext (Phase 2) instead of prompt mutation.
-        Validation runs against the original prompt, eliminating T3 false positives.
+        Builds project context and caches it for SubagentStart to forward.
+        PreToolUse no longer returns additionalContext directly -- that would
+        inject it into the orchestrator instead of the subagent.
         """
         from modules.core.state import create_pre_hook_state, save_hook_state
         from modules.tools.task_validator import TaskValidator
@@ -575,18 +613,48 @@ class ClaudeCodeAdapter(HookAdapter):
 
         logger.info("ALLOWED Task: %s", result.agent_name)
 
+        # Cache context for SubagentStart to pick up and forward to the subagent.
+        # PreToolUse:Agent additionalContext goes to the orchestrator (wrong target).
         additional = "\n".join(filter(None, [context_text, events_text]))
+
+        # Fallback: if build_project_context returned None because the
+        # orchestrator already embedded context in the prompt (dedup guard),
+        # extract the embedded context so SubagentStart can still inject it
+        # via additionalContext.
+        if not additional:
+            prompt = parameters.get("prompt", "")
+            marker = "# Project Context"
+            if marker in prompt:
+                # Extract everything from the marker onwards as context.
+                # The orchestrator copied its own injected context into the
+                # Agent tool prompt; we forward it to SubagentStart instead.
+                idx = prompt.index(marker)
+                additional = prompt[idx:]
+                logger.info(
+                    "Extracted embedded context from prompt for caching "
+                    "(len=%d, agent=%s)",
+                    len(additional), result.agent_name,
+                )
+
         if additional:
-            logger.info("Returning additionalContext for %s (context injected)", result.agent_name)
-            output = {
-                "hookSpecificOutput": {
-                    "hookEventName": "PreToolUse",
-                    "permissionDecision": "allow",
-                    "permissionDecisionReason": f"Context injected for {result.agent_name}",
-                    "additionalContext": additional,
-                }
-            }
-            return HookResponse(output=output, exit_code=0)
+            effective_session_id = session_id or "unknown"
+            agent_type = result.agent_name or "unknown"
+            self._cache_context_for_subagent(effective_session_id, agent_type, additional)
+            logger.info(
+                "Cached context for SubagentStart: agent=%s, session=%s",
+                agent_type, effective_session_id,
+            )
+
+        # Write AGENT_DISPATCH event (non-blocking)
+        try:
+            from modules.events.event_writer import EventWriter, AGENT_DISPATCH
+            prompt = parameters.get("prompt", "")
+            EventWriter().write_event(
+                AGENT_DISPATCH, "hook", result.agent_name or "unknown",
+                f"dispatched for: {prompt[:100]}",
+            )
+        except Exception:
+            pass  # Events are non-critical
 
         return HookResponse(output={}, exit_code=0)
 
@@ -595,8 +663,9 @@ class ClaudeCodeAdapter(HookAdapter):
     ) -> HookResponse:
         """Handle SendMessage tool validation for agent resumption.
 
-        Validates agent ID format and message content, then runs nonce
-        approval checks. Does NOT inject project context (it's a resume).
+        Validates agent ID format and message content. Does NOT inject
+        project context (it's a resume). Nonce relay is no longer processed
+        here -- approval grants are activated by the UserPromptSubmit hook.
         """
         from modules.core.state import create_pre_hook_state, save_hook_state
 
@@ -630,74 +699,19 @@ class ClaudeCodeAdapter(HookAdapter):
 
         logger.info("SENDMESSAGE: Resuming agent %s", agent_id)
 
-        approval_error, has_approval = self._adapt_resume_approval(agent_id, message)
-        if approval_error:
-            return HookResponse(output=approval_error, exit_code=2)
-
         state = create_pre_hook_state(
             tool_name=tool_name,
             command=f"SendMessage:{agent_id}",
             tier="T0",
             allowed=True,
             is_t3=False,
-            has_approval=has_approval,
+            has_approval=False,
         )
         save_hook_state(state)
 
         logger.info("ALLOWED SendMessage: agent %s - message length: %d", agent_id, len(message))
         return HookResponse(output={}, exit_code=0)
 
-    def _adapt_resume_approval(
-        self, resume_id: str, prompt: str,
-    ) -> tuple[str | None, bool]:
-        """Process nonce approval indicators for Task resume."""
-        from modules.security.approval_constants import NONCE_APPROVAL_PATTERN
-        from modules.security.approval_messages import (
-            build_activation_failed_message,
-            build_deprecated_approval_message,
-            build_invalid_nonce_message,
-        )
-        from modules.security.approval_grants import activate_pending_approval
-        from modules.security.prompt_validator import classify_resume_prompt
-
-        classification = classify_resume_prompt(prompt)
-
-        if classification == "nonce":
-            nonce = NONCE_APPROVAL_PATTERN.search(prompt).group(1)
-            activation = activate_pending_approval(nonce)
-            status_text = getattr(activation.status, "value", str(activation.status))
-            if activation.success:
-                grant_path = activation.grant_path
-                grant_name = grant_path.name if grant_path else "<unknown>"
-                logger.info(
-                    "Nonce approval activated for resume %s: nonce=%s, file=%s",
-                    resume_id, nonce, grant_name,
-                )
-                return None, True
-
-            logger.warning(
-                "Denied resume %s: nonce approval activation failed for nonce=%s "
-                "(status=%s, reason=%s)",
-                resume_id, nonce, status_text, activation.reason,
-            )
-            return build_activation_failed_message(nonce, status_text, activation.reason), False
-
-        if classification == "malformed_nonce":
-            logger.warning(
-                "Denied resume %s: malformed nonce approval token in prompt='%s'",
-                resume_id, prompt[:120],
-            )
-            return build_invalid_nonce_message(), False
-
-        if classification == "deprecated":
-            logger.warning(
-                "Denied resume %s: deprecated legacy approval phrase detected",
-                resume_id,
-            )
-            return build_deprecated_approval_message(), False
-
-        return None, False
-
     @staticmethod
     def _format_blocked_message(result) -> str:
         """Format blocked command message. Delegates to blocked_message_formatter."""
@@ -713,25 +727,32 @@ class ClaudeCodeAdapter(HookAdapter):
 
         Orchestrates: state retrieval, duration computation, audit logging,
         T3 grant confirmation, critical event detection, session context
-        writing, and state cleanup.
+        writing, state cleanup, and AskUserQuestion grant activation.
         """
         from modules.core.state import get_hook_state, clear_hook_state
         from modules.audit.logger import log_execution
         from modules.audit.event_detector import detect_critical_event
         from modules.session.session_context_writer import SessionContextWriter
-        from modules.security.approval_grants import check_approval_grant, confirm_grant
+        from modules.security.approval_grants import check_approval_grant, confirm_grant, consume_grant
 
         hook_data = event.payload
         tool_result_data = self.parse_post_tool_use(hook_data)
         logger.info("Post-hook event: %s", hook_data.get("hook_event_name"))
 
-        raw_tool_result = hook_data.get("tool_result", {})
+        raw_tool_response = hook_data.get("tool_response", {})
         tool_name = tool_result_data.tool_name
         parameters = hook_data.get("tool_input", {})
         output = tool_result_data.output
-        duration = raw_tool_result.get("duration_ms", 0) / 1000.0
+        duration = raw_tool_response.get("duration_ms", 0) / 1000.0
         success = tool_result_data.exit_code == 0
 
+        # ------------------------------------------------------------- #
+        # AskUserQuestion: check if user approved a pending T3 grant
+        # ------------------------------------------------------------- #
+        if tool_name == "AskUserQuestion":
+            self._handle_ask_user_question_result(hook_data)
+            return HookResponse(output={}, exit_code=0)
+
         try:
             pre_state = get_hook_state()
             tier = pre_state.tier if pre_state else "unknown"
@@ -753,12 +774,14 @@ class ClaudeCodeAdapter(HookAdapter):
             # Confirm unconfirmed T3 grants after successful Bash execution
             if tool_name == "Bash" and success:
                 command = parameters.get("command", "")
+                session_id = hook_data.get("session_id", "")
                 if command:
-                    grant = check_approval_grant(command)
+                    grant = check_approval_grant(command, session_id=session_id)
                     if grant is not None and not grant.confirmed:
-                        confirm_grant(command)
+                        confirm_grant(command, session_id=session_id)
+                        consume_grant(command, session_id=session_id)  # Single-use: mark as consumed
                         logger.info(
-                            "T3 grant confirmed post-execution: %s", command[:80],
+                            "T3 grant confirmed and consumed post-execution: %s", command[:80],
                         )
 
             events = detect_critical_event(tool_name, parameters, output, success)
@@ -767,6 +790,20 @@ class ClaudeCodeAdapter(HookAdapter):
                 for evt in events:
                     writer.update_context(evt.to_dict())
 
+            # Write COMMAND_EXECUTED event for T2+ Bash commands only (non-blocking)
+            if tool_name == "Bash" and tier in ("T2", "T3"):
+                try:
+                    from modules.events.event_writer import EventWriter, COMMAND_EXECUTED
+                    cmd = parameters.get("command", "")
+                    EventWriter().write_event(
+                        COMMAND_EXECUTED, "hook", "",
+                        f"{'ok' if success else 'error'}: {cmd[:120]}",
+                        severity="info" if success else "warning",
+                        meta={"tier": tier},
+                    )
+                except Exception:
+                    pass  # Events are non-critical
+
             clear_hook_state()
             logger.debug("Post-hook completed for %s", tool_name)
 
@@ -775,6 +812,77 @@ class ClaudeCodeAdapter(HookAdapter):
 
         return HookResponse(output={}, exit_code=0)
 
+    # ------------------------------------------------------------------ #
+    # _handle_ask_user_question_result: grant activation from user answer
+    # ------------------------------------------------------------------ #
+
+    def _handle_ask_user_question_result(self, hook_data: Dict[str, Any]) -> None:
+        """Conditionally activate pending grants based on user's answer.
+
+        Inspects the answers dict from tool_response (or tool_input as fallback)
+        to determine if the user approved. Only activates grants when at least
+        one answer value contains "approve" (case-insensitive).
+
+        Never blocks (no exceptions raised to caller).
+        """
+        import json as _json
+        from modules.security.approval_grants import (
+            activate_grants_for_session,
+            get_pending_approvals_for_session,
+        )
+
+        session_id = hook_data.get("session_id", "") or os.environ.get("CLAUDE_SESSION_ID", "")
+
+        # Debug logging
+        tool_response = hook_data.get("tool_response", {})
+        logger.info("AskUserQuestion PostToolUse keys: %s", list(hook_data.keys()))
+        logger.info("AskUserQuestion tool_response: %s", _json.dumps(tool_response, default=str)[:500])
+
+        # Extract answers from tool_response first, then tool_input as fallback
+        answers = {}
+        if isinstance(tool_response, dict):
+            answers = tool_response.get("answers", {})
+        if not answers and isinstance(hook_data.get("tool_input", {}), dict):
+            answers = hook_data.get("tool_input", {}).get("answers", {})
+
+        if not answers:
+            logger.info("AskUserQuestion: no answers found in payload, skipping grant activation")
+            return
+
+        # Check if any answer contains "approve"
+        user_approved = any("approve" in str(v).lower() for v in answers.values())
+
+        if not user_approved:
+            logger.info(
+                "AskUserQuestion: user did not approve (answers: %s), skipping grant activation",
+                {k: v for k, v in answers.items()},
+            )
+            return
+
+        # User approved -- activate grants
+        logger.info("AskUserQuestion: user approved, activating grants for session %s", session_id[:12])
+
+        try:
+            if not session_id:
+                logger.info("AskUserQuestion: no session_id available, skipping grant activation")
+                return
+
+            # Check for pending approvals before activating
+            pending = get_pending_approvals_for_session(session_id)
+            if not pending:
+                logger.info("AskUserQuestion: no pending grants for session %s", session_id)
+                return
+
+            results = activate_grants_for_session(session_id)
+            activated = sum(1 for r in results if r.success)
+            logger.info(
+                "AskUserQuestion activated %d/%d pending grants for session %s",
+                activated, len(results), session_id,
+            )
+
+        except Exception as e:
+            logger.error("Error in _handle_ask_user_question_result: %s", e, exc_info=True)
+
     # ------------------------------------------------------------------ #
     # adapt_subagent_stop: full subagent-stop lifecycle
     # ------------------------------------------------------------------ #
@@ -792,7 +900,6 @@ class ClaudeCodeAdapter(HookAdapter):
             requires_consolidation_report,
             validate as validate_contract,
             validate_approval_request,
-            validate_awaiting_approval_has_nonce,
             validate_verbatim_outputs_consistency,
         )
         from modules.agents.response_contract import (
@@ -986,6 +1093,24 @@ class ClaudeCodeAdapter(HookAdapter):
                 commands_executed=commands_executed,
             )
 
+            # Write AGENT_COMPLETE event (non-blocking)
+            try:
+                from modules.events.event_writer import EventWriter, AGENT_COMPLETE
+                _plan = ""
+                if parsed_contract and isinstance(parsed_contract.get("agent_status"), dict):
+                    _plan = str(parsed_contract["agent_status"].get("plan_status", ""))
+                _key_outputs = []
+                if parsed_contract and isinstance(parsed_contract.get("evidence_report"), dict):
+                    _key_outputs = parsed_contract["evidence_report"].get("key_outputs", [])
+                _summary = "; ".join(str(o) for o in _key_outputs[:2]) if _key_outputs else ""
+                EventWriter().write_event(
+                    AGENT_COMPLETE, "hook", agent_type,
+                    _plan or "completed",
+                    meta={"episode_id": episode_id, "summary": _summary[:200]},
+                )
+            except Exception:
+                pass  # Events are non-critical
+
             contract_attempts = 0
             if not response_contract.valid:
                 try:
@@ -1007,19 +1132,11 @@ class ClaudeCodeAdapter(HookAdapter):
                 )
 
             # ----------------------------------------------------------
-            # False pending-approval detection
-            # Advisory only -- adds to anomalies but never blocks.
+            # Extract plan_status for downstream checks
             # ----------------------------------------------------------
             _plan_status = ""
             if parsed_contract and isinstance(parsed_contract.get("agent_status"), dict):
                 _plan_status = str(parsed_contract["agent_status"].get("plan_status", ""))
-            false_pa_check = validate_awaiting_approval_has_nonce(agent_output, _plan_status)
-            if false_pa_check:
-                anomalies.append(false_pa_check)
-                logger.info(
-                    "AWAITING_APPROVAL without nonce for %s: %s",
-                    agent_type, false_pa_check.get("detail", ""),
-                )
 
             # ----------------------------------------------------------
             # Approval request validation
@@ -1145,9 +1262,16 @@ class ClaudeCodeAdapter(HookAdapter):
             QualityResult with quality assessment.
             Default: quality_sufficient=True (passthrough until business logic wired).
         """
-        # Extract stop reason and response content for future quality checks
-        _stop_reason = raw.get("stop_reason", "")
-        _last_message = raw.get("last_assistant_message", "")
+        # Write SESSION_END event (non-blocking)
+        try:
+            from modules.events.event_writer import EventWriter, SESSION_END
+            stop_reason = raw.get("stop_reason", "unknown")
+            EventWriter().write_event(
+                SESSION_END, "hook", "",
+                f"session ended: {stop_reason}",
+            )
+        except Exception:
+            pass  # Events are non-critical
 
         return QualityResult(
             quality_sufficient=True,
@@ -1170,10 +1294,6 @@ class ClaudeCodeAdapter(HookAdapter):
             VerificationResult with criteria assessment.
             Default: criteria_met=True (passthrough until business logic wired).
         """
-        # Extract task details for future verification logic
-        _task_id = raw.get("task_id", "")
-        _task_output = raw.get("task_output", "")
-
         return VerificationResult(
             criteria_met=True,
             verified_items=[],
@@ -1181,15 +1301,134 @@ class ClaudeCodeAdapter(HookAdapter):
             block_completion=False,
         )
 
+    # ------------------------------------------------------------------ #
+    # Context cache: PreToolUse -> SubagentStart bridge
+    # ------------------------------------------------------------------ #
+
+    CONTEXT_CACHE_DIR = Path("/tmp/gaia-context-cache")
+    CONTEXT_CACHE_TTL_SECONDS = 60  # Cache entries older than this are stale
+
+    def _cache_context_for_subagent(
+        self, session_id: str, agent_type: str, context: str,
+    ) -> Path:
+        """Write built context to a cache file for SubagentStart consumption.
+
+        Returns the path to the cache file.
+        """
+        self.CONTEXT_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        timestamp = int(time.time() * 1000)
+        cache_file = self.CONTEXT_CACHE_DIR / f"{session_id}-{timestamp}.json"
+        payload = {
+            "context": context,
+            "agent_type": agent_type,
+            "session_id": session_id,
+            "created_at": time.time(),
+        }
+        cache_file.write_text(json.dumps(payload))
+        logger.debug("Context cache written: %s", cache_file)
+        return cache_file
+
+    def _read_cached_context(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """Read and consume the most recent cached context for a session.
+
+        Finds the newest cache file matching the session_id, reads it,
+        deletes it (one-shot consumption), and cleans up stale entries.
+
+        Returns None if no cache is found.
+        """
+        if not self.CONTEXT_CACHE_DIR.exists():
+            return None
+
+        # Find all cache files for this session, sorted newest-first
+        candidates: List[Path] = sorted(
+            self.CONTEXT_CACHE_DIR.glob(f"{session_id}-*.json"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+
+        if not candidates:
+            # Fallback: try to find the most recent cache file regardless of
+            # session_id, since the orchestrator session_id and the subagent
+            # session_id may differ.
+            all_files = sorted(
+                self.CONTEXT_CACHE_DIR.glob("*.json"),
+                key=lambda p: p.stat().st_mtime,
+                reverse=True,
+            )
+            candidates = all_files
+
+        now = time.time()
+        result = None
+
+        for cache_file in candidates:
+            try:
+                data = json.loads(cache_file.read_text())
+                age = now - data.get("created_at", 0)
+
+                if age > self.CONTEXT_CACHE_TTL_SECONDS:
+                    # Stale entry -- clean up
+                    cache_file.unlink(missing_ok=True)
+                    logger.debug("Cleaned stale context cache: %s (age=%.1fs)", cache_file.name, age)
+                    continue
+
+                # Found a valid entry -- consume it
+                result = data
+                cache_file.unlink(missing_ok=True)
+                logger.debug("Consumed context cache: %s (age=%.1fs)", cache_file.name, age)
+                break
+
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.warning("Failed to read context cache %s: %s", cache_file, exc)
+                cache_file.unlink(missing_ok=True)
+                continue
+
+        # Clean up any remaining stale files (background hygiene)
+        self._cleanup_stale_cache(now)
+
+        return result
+
+    def _cleanup_stale_cache(self, now: float) -> None:
+        """Remove cache files older than TTL."""
+        if not self.CONTEXT_CACHE_DIR.exists():
+            return
+        for f in self.CONTEXT_CACHE_DIR.glob("*.json"):
+            try:
+                data = json.loads(f.read_text())
+                if now - data.get("created_at", 0) > self.CONTEXT_CACHE_TTL_SECONDS:
+                    f.unlink(missing_ok=True)
+            except (json.JSONDecodeError, OSError):
+                f.unlink(missing_ok=True)
+
     # ------------------------------------------------------------------ #
     # P2: adapt_subagent_start
     # ------------------------------------------------------------------ #
 
     def adapt_subagent_start(self, raw: dict) -> ContextResult:
-        """Parse SubagentStart event. Context injection is handled by PreToolUse."""
-        _agent_type = raw.get("agent_type", "")
-        _task_description = raw.get("task_description", "")
+        """Parse SubagentStart event and forward cached context to the subagent.
+
+        PreToolUse:Agent caches the built project context. This method reads
+        the cache and returns it as additionalContext so Claude Code injects
+        it into the subagent (not the orchestrator).
+        """
+        session_id = raw.get("session_id", "")
 
+        cached = self._read_cached_context(session_id)
+        if cached:
+            logger.info(
+                "SubagentStart: forwarding cached context for agent=%s (session=%s)",
+                cached.get("agent_type", "unknown"),
+                session_id,
+            )
+            return ContextResult(
+                context_injected=True,
+                additional_context=cached["context"],
+                sections_provided=[],
+            )
+
+        logger.info(
+            "SubagentStart: no cached context found for session=%s (passthrough)",
+            session_id,
+        )
         return ContextResult(
             context_injected=False,
             additional_context=None,