@jaguilar87/gaia 5.1.0 → 5.1.1

package/hooks/README.md

@@ -4,7 +4,7 @@ Hooks are the event-driven spine of Gaia. Every significant moment in a Claude C
 
 Each hook is a Python script that reads a JSON event from stdin, processes it, and writes a JSON response to stdout. Claude Code calls these scripts synchronously before or after each tool execution, which means the hook can allow, modify, or block the operation. The hook cannot do complex async work — it runs inline, in the critical path, so every module it calls must complete quickly.
 
-The hooks form a pipeline. A session opens at `session_start.py`, which emits a one-shot `additionalContext` manifest (Environment, Active Agentic Loop, [ACTIONABLE] pending approvals) for the orchestrator. Each prompt then enters at `user_prompt_submit.py`, gets routed to an agent, triggers `pre_tool_use.py` before each tool call, generates audit records in `post_tool_use.py`, and closes out in `subagent_stop.py` when the agent finishes. The session closes at `session_end_hook.py`. The remaining event handlers (`stop_hook.py`, `subagent_start.py`, `task_completed.py`, `pre_compact.py`, `post_compact.py`, `elicitation_result.py`) fire at lifecycle transitions and carry lighter responsibilities.
+The hooks form a pipeline. A session opens at `session_start.py`, which emits a one-shot `additionalContext` manifest (Environment, Active Agentic Loop) for the orchestrator. Each prompt then enters at `user_prompt_submit.py`, gets routed to an agent, triggers `pre_tool_use.py` before each tool call, generates audit records in `post_tool_use.py`, and closes out in `subagent_stop.py` when the agent finishes. The session closes at `session_end_hook.py`. The remaining event handlers (`stop_hook.py`, `subagent_start.py`, `task_completed.py`, `pre_compact.py`, `post_compact.py`, `elicitation_result.py`) fire at lifecycle transitions and carry lighter responsibilities.
 
 ## Cuándo se activa
 
@@ -15,7 +15,7 @@ Session opens
         |  Registers session in heartbeat-based session_registry
         |  Sweeps stale registry entries and expired approval files
         |  Emits one-shot hookSpecificOutput.additionalContext manifest
-        |  (Environment + Active Agentic Loop + [ACTIONABLE] pendings)
+        |  (Environment + Active Agentic Loop)
         v
 User sends prompt
         |

package/hooks/adapters/claude_code.py

@@ -1433,18 +1433,12 @@ class ClaudeCodeAdapter(HookAdapter):
                 preserve_nonces=preserved_nonces if preserved_nonces else None,
             )
 
-            # Consume all confirmed grants for this session -- the subagent
-            # is done, so grants should not survive past its lifetime.
-            try:
-                from modules.security.approval_grants import consume_session_grants
-                consumed = consume_session_grants(session_id)
-                if consumed:
-                    logger.info(
-                        "SubagentStop consumed %d grant(s) for session %s",
-                        consumed, session_id[:12],
-                    )
-            except Exception as exc:
-                logger.debug("Grant consumption at SubagentStop failed (non-fatal): %s", exc)
+            # NOTE (approvals redesign, M1): grants are consumed AT THE MATCH by
+            # bash_validator (PENDING->CONSUMED when the command is authorized in
+            # PreToolUse), NOT swept at SubagentStop. A grant that was never
+            # presented to a matching retry stays PENDING and expires on its own
+            # short (5m) TTL, so it must survive the subagent ending. The former
+            # consume_session_grants() sweep has been removed.
 
             commands_executed = extract_commands_from_evidence(agent_output)
 

package/hooks/elicitation_result.py

@@ -14,7 +14,6 @@ import sys
 import json
 import logging
 import os
-from datetime import datetime
 from pathlib import Path
 
 _hooks_dir = Path(__file__).resolve().parent
@@ -23,16 +22,12 @@ _pkg_root = str(_hooks_dir.parent)
 if _pkg_root not in sys.path:
     sys.path.insert(0, _pkg_root)
 
-from modules.core.paths import get_logs_dir
+from modules.core.logging_setup import configure_hook_logging
 from modules.core.stdin import has_stdin_data
 
-# Configure logging -- file only, no stderr
-_log_file = get_logs_dir() / f"hooks-{datetime.now().strftime('%Y-%m-%d')}.log"
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s [elicitation_result] %(name)s - %(levelname)s - %(message)s',
-    handlers=[logging.FileHandler(_log_file)],
-)
+# Configure logging -- file handler only when GAIA_DEBUG is set; no
+# hooks-*.log is written by default (see modules.core.logging_setup).
+configure_hook_logging("elicitation_result")
 logger = logging.getLogger(__name__)
 
 

package/hooks/modules/agents/contract_validator.py

@@ -384,7 +384,8 @@ def requires_consolidation_report(task_info: Dict[str, Any]) -> bool:
         # Fallback: read from transcript if injected_context was not pre-extracted
         from .transcript_reader import extract_injected_context_payload_from_transcript
         payload = extract_injected_context_payload_from_transcript(
-            task_info.get("agent_transcript_path", "")
+            task_info.get("agent_transcript_path", ""),
+            task_info.get("agent", ""),
         )
     if not payload:
         return False

package/hooks/modules/agents/handoff_persister.py

@@ -17,191 +17,6 @@ import logging
 logger = logging.getLogger(__name__)
 
 
-def _normalize_command_set(raw) -> list:
-    """Coerce a raw ``command_set`` into the canonical ``[{command, rationale}]``.
-
-    Mirrors the normalization in ``bash_validator._build_sealed_payload`` and
-    ``approval_grants.activate_db_pending_by_prefix`` so the intake writes the
-    exact shape the activation/consume sides expect. Items without a non-empty
-    ``command`` are dropped; ``rationale`` defaults to "".
-    """
-    out: list = []
-    if isinstance(raw, list):
-        for item in raw:
-            if isinstance(item, dict) and item.get("command"):
-                out.append(
-                    {
-                        "command": item["command"],
-                        "rationale": item.get("rationale", ""),
-                    }
-                )
-    return out
-
-
-def _filter_mutative_command_set(items: list) -> list:
-    """Keep only the command_set items whose command is mutative/T3.
-
-    The consume side (``bash_validator._validate_single_command``) gates the
-    whole COMMAND_SET match path on ``detect_mutative_command(command).is_mutative``:
-    a command that the matcher does not see as mutative NEVER reaches
-    ``match_command_set_grant`` and its index is therefore NEVER consumed. If
-    such a command is included in the grant's ``command_set``, ``len(consumed)``
-    can never reach ``len(command_set)`` and the grant is stuck PENDING forever
-    (it never flips to CONSUMED). To stay in lockstep with the consume gate, the
-    intake filters with the EXACT same predicate, dropping non-mutative commands
-    (e.g. ``touch``, ``ls``, ``cat``) before the grant is ever minted.
-
-    Items that fail to classify (import error, unexpected exception) are kept --
-    failing open here is safer than silently dropping a command from a consent
-    batch the user is about to approve.
-    """
-    try:
-        from modules.security.mutative_verbs import detect_mutative_command
-    except ImportError:
-        import pathlib as _pl
-        import sys as _sys
-
-        _hooks_root = _pl.Path(__file__).resolve().parent.parent.parent
-        _sys.path.insert(0, str(_hooks_root))
-        from modules.security.mutative_verbs import detect_mutative_command
-
-    kept: list = []
-    for item in items:
-        command = item.get("command", "")
-        try:
-            if detect_mutative_command(command).is_mutative:
-                kept.append(item)
-        except Exception:
-            # Fail open: if classification raises, keep the item rather than
-            # silently dropping a command from the user's consent batch.
-            kept.append(item)
-    return kept
-
-
-def _intake_command_set_pending(
-    approval_req: dict,
-    *,
-    agent_id,
-    session_id: str,
-) -> str | None:
-    """INTAKE bridge: plan-first COMMAND_SET envelope -> ONE pending row.
-
-    When a subagent emits an ``APPROVAL_REQUEST`` whose ``approval_request``
-    carries a ``command_set`` of >= 2 ``{command, rationale}`` items and NO
-    ``approval_id`` (plan-first: the batch is declared up-front, before any
-    command was attempted/blocked), this persists exactly ONE pending approval
-    whose ``payload_json`` contains the ``command_set`` key. That is the signal
-    ``activate_db_pending_by_prefix`` reads (Step 3b) to branch into
-    ``create_command_set_grant`` on user approval.
-
-    Mutative filtering (Thread a): the command_set is first reduced to ONLY the
-    commands the consume side will treat as mutative/T3 -- see
-    ``_filter_mutative_command_set``. Non-mutative commands (``touch``, ``ls``,
-    ...) never reach the bash_validator matcher, so leaving them in the grant
-    would strand its ``consumed_indexes_json`` short of completion and pin the
-    grant at PENDING forever. After filtering:
-
-      * >= 2 mutative items  -> mint the COMMAND_SET over exactly those items.
-      * exactly 1 mutative   -> NOT a batch. Return None; the caller falls
-        through to the singular ``approval_id`` path and the lone command is
-        gated by the normal hook-block / SCOPE_SEMANTIC_SIGNATURE flow when the
-        agent attempts it. We deliberately do NOT degrade-to-singular here: this
-        function's contract is "mint a COMMAND_SET or stand aside", and the
-        singular flow is owned end-to-end by the hook block path -- minting a
-        singular row from here would duplicate that ownership.
-      * 0 mutative           -> nothing to approve. Return None (no pending).
-
-    A raw ``command_set`` of <= 1 item is likewise not a batch and returns None
-    before filtering, preserving the original contract (never mint for one
-    command, never degrade a batch the other way) and the working plan-first
-    flow for genuine multi-command mutative batches.
-
-    Returns the minted ``approval_id`` (``P-{uuid4hex}``) on success, or None
-    when this is not a plan-first command_set envelope (no action taken).
-    """
-    if not isinstance(approval_req, dict):
-        return None
-    # Plan-first is defined by command_set present AND no approval_id. A request
-    # that already carries an approval_id was minted by the hook block path; it
-    # is the singular flow and must not be re-intaken here.
-    if approval_req.get("approval_id"):
-        return None
-
-    raw_items = _normalize_command_set(approval_req.get("command_set"))
-    if len(raw_items) < 2:
-        # 0 or 1 item: not a batch. Singular path owns it.
-        return None
-
-    # Reduce to the mutative/T3 commands only -- the exact predicate the consume
-    # side uses to decide whether a command reaches the COMMAND_SET matcher.
-    command_set_items = _filter_mutative_command_set(raw_items)
-    if len(command_set_items) < 2:
-        # After filtering there is no batch left: either every command was
-        # non-mutative (0 -> nothing to approve) or just one mutative command
-        # remained (1 -> singular path owns it). Either way, no COMMAND_SET.
-        logger.info(
-            "INTAKE: command_set not minted -- %d/%d items mutative after filter "
-            "(need >= 2 for a batch)",
-            len(command_set_items), len(raw_items),
-        )
-        return None
-
-    # Build a sealed_payload that mirrors bash_validator._build_sealed_payload's
-    # COMMAND_SET shape: command_set verbatim + commands listing every string.
-    # Carry through the subagent's operation/risk fields when present so the
-    # orchestrator's presentation has real values, falling back to neutral
-    # COMMAND_SET defaults otherwise.
-    first_command = command_set_items[0]["command"]
-    sealed_payload = {
-        "operation": approval_req.get("operation")
-        or f"COMMAND_SET intercepted: {len(command_set_items)} commands under one consent",
-        "exact_content": approval_req.get("exact_content") or first_command,
-        "scope": approval_req.get("scope")
-        or (first_command.split()[0] if first_command.strip() else "unknown"),
-        "risk_level": approval_req.get("risk_level") or "medium",
-        "rollback_hint": approval_req.get("rollback") or approval_req.get("rollback_hint"),
-        "rationale": approval_req.get("rationale")
-        or (
-            f"A batch of {len(command_set_items)} related T3 commands requires user "
-            "approval under one consent per the COMMAND_SET policy."
-        ),
-        "commands": [it["command"] for it in command_set_items],
-        "command_set": command_set_items,
-    }
-
-    try:
-        from gaia.approvals.store import derive_command_set_id, insert_requested
-    except ImportError:
-        import pathlib as _pl
-        import sys as _sys
-
-        _repo_root = _pl.Path(__file__).resolve().parent.parent.parent.parent
-        _sys.path.insert(0, str(_repo_root))
-        from gaia.approvals.store import derive_command_set_id, insert_requested
-
-    # Derive the PUBLIC approval_id deterministically from the post-filter
-    # mutative command strings. Because the id is content-derived (not uuid4),
-    # the orchestrator reproduces the SAME id from the command_set it reads in
-    # the contract via `gaia approvals derive-id` -- no DB search, no
-    # cross-session miss. The list passed here is the SAME list the CLI helper
-    # derives over (post-mutative-filter), so both sides agree.
-    derived_id = derive_command_set_id(
-        [it["command"] for it in command_set_items]
-    )
-
-    approval_id = insert_requested(
-        sealed_payload,
-        agent_id=agent_id,
-        session_id=session_id or None,
-        approval_id=derived_id,
-    )
-    logger.info(
-        "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",
-        (approval_id or "")[:16], len(command_set_items),
-    )
-    return approval_id
-
-
 def persist_handoff(
     parsed_contract,
     agent_output: str,
@@ -227,36 +42,6 @@ def persist_handoff(
 
     agent_id = task_info.get("agent_id") or task_info.get("agent") or "unknown"
 
-    # ---------------------------------------------------------------------
-    # INTAKE bridge (plan-first COMMAND_SET) -- run FIRST and INDEPENDENTLY.
-    #
-    # Minting the pending COMMAND_SET approval is the security-critical path:
-    # it is the consent the user must act on. It must not be coupled to the
-    # audit handoff-row write below -- if insert_agent_contract_handoff fails
-    # for any reason, the user must still get the approval to review. So the
-    # intake runs in its own isolated try, before the handoff-row write.
-    #
-    # Only plan-first envelopes act here: command_set >= 2 items AND no
-    # approval_id. A <= 1 item set or a request that already carries an
-    # approval_id (hook-block / singular path) is a no-op for the intake.
-    # ---------------------------------------------------------------------
-    minted_command_set_id = None
-    if parsed_contract is not None:
-        _env = parsed_contract if isinstance(parsed_contract, dict) else {}
-        _approval_req = _env.get("approval_request")
-        if isinstance(_approval_req, dict):
-            try:
-                minted_command_set_id = _intake_command_set_pending(
-                    _approval_req,
-                    agent_id=agent_id,
-                    session_id=session_id,
-                )
-            except Exception as _intake_exc:
-                logger.warning(
-                    "M4: COMMAND_SET intake failed (non-blocking): %s",
-                    _intake_exc,
-                )
-
     try:
         # Prefer a sibling gaia package if installed; fall back to the repo
         # layout where gaia/ lives two levels above hooks/.
@@ -317,11 +102,11 @@ def persist_handoff(
             envelope = parsed_contract if isinstance(parsed_contract, dict) else {}
             approval_req = envelope.get("approval_request")
             if approval_req and isinstance(approval_req, dict):
-                # The approval_id is either the one the subagent relayed (hook-block
-                # / singular path) or the one the INTAKE bridge just minted for a
-                # plan-first COMMAND_SET. Either way it points at the pending row
-                # the handoff_approvals audit row should link to.
-                approval_id = approval_req.get("approval_id") or minted_command_set_id
+                # The approval_id is the one the subagent relayed (the hook-block
+                # / singular path, or a compound-command COMMAND_SET minted by
+                # bash_validator). It points at the pending row the
+                # handoff_approvals audit row should link to.
+                approval_id = approval_req.get("approval_id")
 
                 if approval_id:
                     # Look up the grant to determine the decision at stop time.

package/hooks/modules/agents/task_info_builder.py

@@ -55,8 +55,15 @@ def build_task_info_from_hook_data(
     # Extract real task description from the first user message in the transcript
     transcript_path = hook_data.get("agent_transcript_path", "")
     task_description = extract_task_description_from_transcript(transcript_path)
-    injected_context = extract_injected_context_payload_from_transcript(transcript_path)
-    agent_type = hook_data.get("agent_type", "") or "unknown"
+    # Resolve agent name first: it is the key the context payload is stored
+    # under (context_injector writes f"{subagent_type}.json"), so the reader
+    # needs it to find the payload. The bare hook_data value (not the "unknown"
+    # default) is the write-side key.
+    agent_type_raw = hook_data.get("agent_type", "")
+    injected_context = extract_injected_context_payload_from_transcript(
+        transcript_path, agent_type_raw
+    )
+    agent_type = agent_type_raw or "unknown"
     if not task_description:
         task_description = f"SubagentStop for {agent_type}"
 

package/hooks/modules/agents/transcript_reader.py

@@ -96,35 +96,55 @@ def extract_task_description_from_transcript(transcript_path: str) -> str:
 
 def extract_injected_context_payload_from_transcript(
     transcript_path: str,
+    agent_type: str = "",
 ) -> Dict[str, Any]:
     """Extract the auto-injected context payload from disk cache.
 
     Context is delivered via additionalContext and the payload is persisted to
     disk by context_injector. Prompts do not contain embedded payloads.
-    """
-    # 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
-    # (and return) the FIRST payload sitting in gaia-context-payloads/, making
-    # the result depend on whatever happens to be in that directory. Mirror the
-    # guard in read_first_user_content_from_transcript: no path, no match.
-    if not transcript_path:
-        return {}
 
+    The payload is written by context_injector.build_project_context keyed by
+    agent name: ``gaia-context-payloads/{agent_name}.json``. The reliable way to
+    find it is therefore ``agent_type`` (the SubagentStop event's ``agent_type``
+    / task_info ``agent``), which equals the write side's ``subagent_type``.
+
+    The legacy transcript-stem substring match is retained as a fallback for
+    callers that cannot supply ``agent_type`` -- but it never intersects the
+    write key (a transcript stem like ``agent-ae190a4da68d626d4`` shares no
+    substring with an agent name like ``developer``), so passing ``agent_type``
+    is what actually populates the context-snapshot telemetry.
+    """
     try:
         payload_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "gaia-context-payloads"
-        if payload_dir.exists():
-            agent_file = Path(transcript_path).stem  # e.g. "agent-ae190a4da68d626d4"
-            # A stem that came out empty (e.g. path was "/" or "."): nothing to
-            # match against, so the substring test would again degrade to the
-            # always-true ``"" in candidate.stem``. Bail rather than grab an
-            # arbitrary payload.
-            if not agent_file:
-                return {}
-            # Match by agent ID substring
-            for candidate in payload_dir.glob("*.json"):
-                if candidate.stem in agent_file or agent_file in candidate.stem:
-                    return json.loads(candidate.read_text())
+        if not payload_dir.exists():
+            return {}
+
+        # Primary lookup: keyed by agent name, matching the write side.
+        if agent_type:
+            candidate = payload_dir / f"{agent_type}.json"
+            if candidate.exists():
+                return json.loads(candidate.read_text())
+
+        # Legacy fallback: transcript-stem substring match.
+        # 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 (and return) the FIRST payload
+        # sitting in gaia-context-payloads/, making the result depend on
+        # whatever happens to be in that directory. Mirror the guard in
+        # read_first_user_content_from_transcript: no path, no match.
+        if not transcript_path:
+            return {}
+        agent_file = Path(transcript_path).stem  # e.g. "agent-ae190a4da68d626d4"
+        # A stem that came out empty (e.g. path was "/" or "."): nothing to
+        # match against, so the substring test would again degrade to the
+        # always-true ``"" in candidate.stem``. Bail rather than grab an
+        # arbitrary payload.
+        if not agent_file:
+            return {}
+        for candidate in payload_dir.glob("*.json"):
+            if candidate.stem in agent_file or agent_file in candidate.stem:
+                return json.loads(candidate.read_text())
     except Exception:
         pass
     return {}

package/hooks/modules/audit/logger.py

@@ -10,7 +10,7 @@ import os
 import json
 import logging
 from pathlib import Path
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Dict, Any, Optional
 
 from ..core.paths import get_logs_dir
@@ -56,7 +56,11 @@ class AuditLogger:
             exit_code: Exit code (0 = success)
             tier: Security tier
         """
-        timestamp = datetime.now().isoformat()
+        # UTC, not local time: gaia metrics (bin/cli/metrics.py) filters
+        # "today" / anomaly windows by comparing against
+        # datetime.now(timezone.utc) -- a naive local timestamp here would
+        # silently drift the Activity Today section by the host's UTC offset.
+        timestamp = datetime.now(timezone.utc).isoformat()
 
         # Extract command for bash tools
         command = ""
@@ -76,7 +80,8 @@ class AuditLogger:
         }
 
         # Write to daily audit log (session log removed — was always "session-default.jsonl")
-        daily_log_file = self.log_dir / f"audit-{datetime.now().strftime('%Y-%m-%d')}.jsonl"
+        # Filename rotates on UTC midnight, matching `timestamp` above.
+        daily_log_file = self.log_dir / f"audit-{datetime.now(timezone.utc).strftime('%Y-%m-%d')}.jsonl"
         self._write_record(daily_log_file, audit_record)
 
         logger.debug(f"Logged execution: {tool_name} - {command[:50]} - {duration:.2f}s")

package/hooks/modules/context/context_injector.py

@@ -403,12 +403,19 @@ def build_project_context(
             orientation_lines.append("- **Metadata** -- session and environment metadata; use for debugging and traceability")
         orientation_section = "\n".join(orientation_lines) + "\n"
 
-        # Save context_payload to disk for downstream hooks (SubagentStop)
+        # Save context_payload to disk for downstream hooks (SubagentStop).
+        # Keyed by agent name (subagent_type): it is the ONLY identifier that
+        # both this PreToolUse write side and the SubagentStop read side share
+        # reliably. The subagent's transcript hash does not exist yet at
+        # dispatch time, and the previously-used parameters['_agent_id'] was
+        # never populated anywhere in the codebase (it always fell through to
+        # subagent_type), so it was not a usable key. The read side
+        # (transcript_reader.extract_injected_context_payload_from_transcript)
+        # must resolve the same f"{agent_name}.json" name.
         try:
             payload_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "gaia-context-payloads"
             payload_dir.mkdir(parents=True, exist_ok=True)
-            agent_id = parameters.get("_agent_id", "") or subagent_type
-            payload_path = payload_dir / f"{agent_id}.json"
+            payload_path = payload_dir / f"{subagent_type}.json"
             payload_path.write_text(json.dumps(context_payload, separators=(',', ':')))
             logger.debug(f"Context payload saved to {payload_path}")
         except Exception as exc:

package/hooks/modules/core/__init__.py

@@ -6,20 +6,21 @@ Provides:
 - plugin_mode: Plugin registry membership check (has_plugin)
 - state: Pre/post hook state sharing
 - stdin: Stdin availability check (has_stdin_data)
+- logging_setup: Shared hook logging config (configure_hook_logging)
 """
 
-from .paths import find_claude_dir, get_plugin_data_dir, get_logs_dir, get_metrics_dir, get_memory_dir
+from .paths import find_claude_dir, get_plugin_data_dir, get_logs_dir, get_memory_dir
 from .plugin_mode import has_plugin
 from .state import HookState, get_hook_state, save_hook_state, clear_hook_state, get_session_id
 from .stdin import has_stdin_data
 from .hook_entry import run_hook
+from .logging_setup import configure_hook_logging
 
 __all__ = [
     # Paths
     "find_claude_dir",
     "get_plugin_data_dir",
     "get_logs_dir",
-    "get_metrics_dir",
     "get_memory_dir",
     # Plugin registry
     "has_plugin",
@@ -33,4 +34,6 @@ __all__ = [
     "has_stdin_data",
     # Hook entry
     "run_hook",
+    # Logging
+    "configure_hook_logging",
 ]

package/hooks/modules/core/logging_setup.py

@@ -0,0 +1,60 @@
+"""
+Shared logging setup for hook entry points.
+
+Every hook entry point (pre_tool_use, post_tool_use, session_start, ...)
+used to wire its own ``logging.basicConfig(handlers=[FileHandler(...)])``
+writing to ``.claude/logs/hooks-YYYY-MM-DD.log``. That log is plain-text
+Python debug output with no schema and no consumer -- unlike the audit log
+(``modules.audit.logger``), nothing in Gaia reads it back. Writing it on
+every turn, by default, in every installation, was pure noise.
+
+``configure_hook_logging()`` centralizes that wiring in one place and gates
+the file handler behind ``GAIA_DEBUG``: by default, hook loggers attach a
+``NullHandler`` (``logger.info(...)`` / ``.error(...)`` calls become cheap
+no-ops and no file is created). Set ``GAIA_DEBUG=1`` to opt into the old
+behavior for local troubleshooting.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime
+
+from .paths import get_logs_dir
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+
+def _debug_enabled() -> bool:
+    """Whether GAIA_DEBUG opts the caller into file-based hook logging."""
+    return os.environ.get("GAIA_DEBUG", "").strip().lower() in _TRUE_VALUES
+
+
+def configure_hook_logging(hook_name: str) -> None:
+    """Configure root logging for a hook entry point.
+
+    Args:
+        hook_name: Human-readable hook name used in the log format's
+            bracketed prefix when file logging is enabled (matches the
+            entry point's file name, e.g. "pre_tool_use").
+
+    By default (``GAIA_DEBUG`` unset), attaches a ``NullHandler`` to the
+    root logger so hook code that calls ``logger.info``/``.warning``/
+    ``.error`` is a cheap no-op and no ``hooks-*.log`` file is created.
+    When ``GAIA_DEBUG`` is truthy, attaches a ``FileHandler`` writing to
+    ``.claude/logs/hooks-YYYY-MM-DD.log``, matching the previous default
+    behavior, for local debugging.
+    """
+    root = logging.getLogger()
+    if _debug_enabled():
+        log_file = get_logs_dir() / f"hooks-{datetime.now().strftime('%Y-%m-%d')}.log"
+        logging.basicConfig(
+            level=logging.INFO,
+            format=f"%(asctime)s [{hook_name}] %(name)s - %(levelname)s - %(message)s",
+            handlers=[logging.FileHandler(log_file)],
+        )
+    elif not root.handlers:
+        root.addHandler(logging.NullHandler())
+
+
+__all__ = ["configure_hook_logging"]

package/hooks/modules/core/paths.py

@@ -96,18 +96,6 @@ def get_logs_dir() -> Path:
     return logs_dir
 
 
-def get_metrics_dir() -> Path:
-    """
-    Get the metrics directory, creating it if necessary.
-
-    Returns:
-        Path to .claude/metrics/
-    """
-    metrics_dir = get_plugin_data_dir() / "metrics"
-    metrics_dir.mkdir(parents=True, exist_ok=True)
-    return metrics_dir
-
-
 def get_memory_dir(subdir: Optional[str] = None) -> Path:
     """
     Get the memory directory, creating it if necessary.