aiwcli 0.9.8 → 0.10.0

package/dist/templates/_shared/lib/base/hook_utils.py

@@ -8,16 +8,90 @@ Provides standardized boilerplate for:
 """
 
 import json
+import os
 import sys
+from datetime import datetime, timezone
 from functools import wraps
 from pathlib import Path
 from typing import Any, Callable, Dict, Optional, TypeVar
 
-from .utils import eprint
+from .logger import log_hook_error, hook_log, log_debug, log_info, log_warn, log_error, log_diagnostic, set_context_path
+
+
+# Context window baseline: tokens not visible in hook data
+# (system prompt, tools, MCP tokens)
+# See: https://github.com/anthropics/claude-code/issues/13783
+CONTEXT_BASELINE_TOKENS = 22_600
+DEFAULT_CONTEXT_WINDOW_SIZE = 200_000
+
+
+def parse_context_window(hook_input: dict) -> tuple:
+    """Parse context window from hook input.
+
+    Returns (tokens_used, max_tokens) or (None, None).
+    tokens_used includes baseline offset for system prompt/tools.
+    """
+    context_window = hook_input.get("context_window")
+    if not context_window:
+        return None, None
+    current_usage = context_window.get("current_usage")
+    if not current_usage:
+        return None, None
+    cache_read = current_usage.get("cache_read_input_tokens", 0) or 0
+    input_tokens = current_usage.get("input_tokens", 0) or 0
+    cache_creation = current_usage.get("cache_creation_input_tokens", 0) or 0
+    output_tokens = current_usage.get("output_tokens", 0) or 0
+    content_tokens = cache_read + input_tokens + cache_creation + output_tokens
+    tokens_used = content_tokens + CONTEXT_BASELINE_TOKENS
+    max_tokens = context_window.get("context_window_size") or DEFAULT_CONTEXT_WINDOW_SIZE
+    return tokens_used, max_tokens
+
+
+def get_context_percent_remaining(hook_input: dict) -> tuple:
+    """Get context percentage remaining with context.json fallback.
+
+    Tries two sources in order:
+    1. Hook input context_window data (most accurate, real-time)
+    2. context.json remaining_percentage (written by status_line.py)
+
+    Returns:
+        (percent_remaining, tokens_used, max_tokens) where tokens_used and
+        max_tokens may be None if data came from context.json fallback.
+        Returns (None, None, None) if no data available from either source.
+    """
+    # Source 1: Hook input (most accurate)
+    tokens_used, max_tokens = parse_context_window(hook_input)
+    if tokens_used is not None and max_tokens is not None and max_tokens > 0:
+        remaining = max_tokens - tokens_used
+        percent_remaining = max(0, min(100, int((remaining / max_tokens) * 100)))
+        return percent_remaining, tokens_used, max_tokens
+
+    # Source 2: context.json fallback (written by status_line.py)
+    try:
+        from .utils import project_dir
+        from ..context.context_store import get_context_by_session_id
+
+        session_id = hook_input.get("session_id")
+        if session_id:
+            project_root = project_dir(hook_input)
+            context = get_context_by_session_id(session_id, project_root)
+            if context and context.last_session:
+                pct = context.last_session.get("context_remaining_pct")
+                if pct is not None:
+                    return pct, None, None
+    except Exception:
+        pass  # Fallback failed — degrade gracefully
+
+    return None, None, None
+
 
 # Type variable for generic decorators
 F = TypeVar('F', bound=Callable[..., Any])
 
+# Event metadata stash — populated by load_hook_input(), read by run_hook()
+_last_hook_event: Optional[str] = None
+_last_tool_name: Optional[str] = None
+
 
 def load_hook_input() -> Optional[Dict[str, Any]]:
     """
@@ -26,11 +100,16 @@ def load_hook_input() -> Optional[Dict[str, Any]]:
     Returns:
         Parsed JSON dict, or None if stdin is empty or invalid JSON
     """
+    global _last_hook_event, _last_tool_name
     try:
         input_data = sys.stdin.read().strip()
         if not input_data:
             return None
-        return json.loads(input_data)
+        result = json.loads(input_data)
+        if isinstance(result, dict):
+            _last_hook_event = result.get("hook_event_name")
+            _last_tool_name = result.get("tool_name")
+        return result
     except json.JSONDecodeError:
         return None
 
@@ -89,7 +168,7 @@ def check_skip_persistence(payload: Dict[str, Any], hook_name: str = "hook") ->
 
     metadata = tool_input.get("metadata", {})
     if isinstance(metadata, dict) and metadata.get("skip_persistence"):
-        eprint(f"[{hook_name}] Skipping persistence (skip_persistence flag set)")
+        log_debug(hook_name, "Skipping persistence (skip_persistence flag set)")
         return True
     return False
 
@@ -118,28 +197,137 @@ def safe_hook_main(hook_name: str) -> Callable[[F], F]:
             try:
                 return func(*args, **kwargs)
             except json.JSONDecodeError as e:
-                eprint(f"[{hook_name}] JSON decode error: {e}")
+                import traceback
+                tb = traceback.format_exc()
+                log_hook_error(hook_name, e, traceback_str=tb)
+                log_error(hook_name, f"JSON decode error: {e}")
                 return 0
             except Exception as e:
-                eprint(f"[{hook_name}] Unexpected error: {e}")
                 import traceback
-                eprint(traceback.format_exc())
+                tb = traceback.format_exc()
+                log_hook_error(hook_name, e, traceback_str=tb)
+                log_error(hook_name, f"Unexpected error: {e}", traceback_str=tb)
                 return 0
         return wrapper  # type: ignore
     return decorator
 
 
-def run_hook(main_func: Callable[[], int]) -> None:
+def emit_context(additional_context: str, ensure_ascii: bool = False) -> None:
+    """Emit hookSpecificOutput with additionalContext to stdout.
+
+    Args:
+        additional_context: Context string to inject into Claude's context
+        ensure_ascii: If True, escape non-ASCII characters in JSON output
     """
-    Standard hook entry point wrapper.
+    out = {
+        "hookSpecificOutput": {
+            "additionalContext": additional_context,
+        }
+    }
+    print(json.dumps(out, ensure_ascii=ensure_ascii))
+
 
-    Calls main function and exits with its return code.
+def emit_context_and_block(
+    additional_context: str,
+    reason: str,
+    ensure_ascii: bool = True,
+) -> None:
+    """Emit hookSpecificOutput that denies the tool call with context and reason.
+
+    Args:
+        additional_context: Context string to inject into Claude's context
+        reason: Reason shown to Claude for why the tool call was denied
+        ensure_ascii: If True, escape non-ASCII characters in JSON output
+    """
+    out = {
+        "hookSpecificOutput": {
+            "additionalContext": additional_context,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    print(json.dumps(out, ensure_ascii=ensure_ascii))
+
+
+def _detect_template(script_path: str = "") -> str:
+    """Auto-detect template origin from the hook script path.
+
+    Returns "shared", a template name (e.g., "cc-native"), or "unknown".
+    """
+    import re
+    path = (script_path or (sys.argv[0] if sys.argv else "")).replace("\\", "/")
+    if "/_shared/hooks/" in path or path.startswith("_shared/hooks/"):
+        return "shared"
+    match = re.search(r'_([a-z][a-z0-9-]*)/hooks/', path)
+    if match:
+        return match.group(1)  # e.g., "cc-native"
+    return "unknown"
+
+
+def run_hook(main_func: Callable[[], int], hook_name: str = "unknown") -> None:
+    """
+    Standard hook entry point wrapper with lifecycle logging.
+
+    Logs HOOK_START before calling main, HOOK_END after completion.
+    Catches unhandled exceptions and logs them before exiting cleanly.
 
     Args:
         main_func: Hook main function that returns exit code
+        hook_name: Name of the hook for error logging
 
     Example:
         if __name__ == "__main__":
-            run_hook(main)
+            run_hook(main, "my_hook")
     """
-    raise SystemExit(main_func())
+    import time
+    start_time = time.monotonic()
+    template = _detect_template()
+    event = _last_hook_event or "unknown"
+    tool = _last_tool_name
+
+    # HOOK_START
+    start_data: Dict[str, Any] = {"lifecycle": "start", "template": template, "event": event}
+    if tool:
+        start_data["tool"] = tool
+    log_info(hook_name, "HOOK_START", data=start_data)
+
+    exit_code = 0
+    status = "success"
+    error_info = None
+
+    try:
+        result = main_func()
+        exit_code = result if isinstance(result, int) else 0
+        status = "blocked" if exit_code != 0 else "success"
+    except SystemExit as e:
+        exit_code = e.code if isinstance(e.code, int) else (1 if e.code else 0)
+        status = "blocked" if exit_code != 0 else "success"
+    except Exception as e:
+        import traceback
+        exit_code = 0  # Non-blocking
+        status = "error"
+        error_info = (e, traceback.format_exc())
+
+    # HOOK_END
+    duration_ms = round((time.monotonic() - start_time) * 1000, 1)
+    end_data: Dict[str, Any] = {
+        "lifecycle": "end", "status": status,
+        "duration_ms": duration_ms, "exit_code": exit_code,
+        "template": template,
+    }
+    end_event = _last_hook_event or event  # Re-read after main() populated it
+    end_tool = _last_tool_name or tool
+    end_data["event"] = end_event
+    if end_tool:
+        end_data["tool"] = end_tool
+    if error_info:
+        e, tb = error_info
+        end_data["error_type"] = type(e).__name__
+        log_hook_error(hook_name, e, traceback_str=tb)
+        log_error(hook_name, f"HOOK_END: {e}", data=end_data, traceback_str=tb)
+    elif status == "blocked":
+        log_warn(hook_name, "HOOK_END", data=end_data)
+    else:
+        log_info(hook_name, "HOOK_END", data=end_data)
+
+    raise SystemExit(exit_code)

package/dist/templates/_shared/lib/base/inference.py

@@ -3,10 +3,13 @@
 Provides a unified interface for Claude API calls using the claude CLI.
 Supports multiple model tiers: fast (Haiku), standard (Sonnet), smart (Opus).
 """
+import re
 import subprocess
 import sys
 import os
 from typing import Optional
+
+from .logger import log_debug, log_info, log_warn, log_error
 from dataclasses import dataclass
 
 
@@ -195,3 +198,121 @@ def generate_semantic_summary(prompt: str, timeout: int = 15) -> Optional[str]:
         return None
 
     return summary
+
+
+# System prompt for generating context ID slugs (3-12 keyword tags for folder names)
+CONTEXT_ID_SLUG_PROMPT = """You are extracting keyword tags from a user's request to create a **folder name** for a work session.
+
+## Why This Matters
+
+These tags become part of a context ID like `260206-1959-refactor-webhook-retry-logic`. Users scan lists of 50-100+ such folder names to find past work sessions. Your job is to extract the 3-12 words that make THIS session instantly recognizable among hundreds of others.
+
+Think: "If someone had 100 folders and needed to find this one by scanning names, which words would make it jump out?"
+
+## First Word: Action Verb (REQUIRED)
+
+The first word MUST be a specific action verb. Choose the most precise verb available:
+
+Common: fix, add, implement, refactor, update, create, remove, replace, optimize, debug
+Specific (preferred when they fit): scaffold, instrument, serialize, throttle, migrate, integrate, extract, redesign, restructure, decouple, consolidate, parallelize, configure, deploy, benchmark, normalize, validate, document, deprecate, upstream
+
+## Word Selection: Rarity = Quality
+
+The less common a word is in everyday language, the better it is as an identifier. Apply this mental filter:
+
+BEST (+3):  Proper nouns, brand names, unique identifiers (PostgreSQL, Webpack, OAuth, JWT, CICD)
+GOOD (+2):  Domain-specific technical terms (middleware, pooling, webhook, serialization, throttle)
+OKAY (+1):  Specific common nouns (authentication, redirect, navbar, pagination, dropdown)
+WEAK (-1):  Generic nouns that appear in most prompts (code, file, app, feature, issue, project, stuff, thing)
+BANNED:     See banned list below — these must NEVER appear in output
+
+Select the 3-12 highest-value words. When choosing between two words that mean similar things, always pick the rarer/more specific one.
+
+## Banned Words (NEVER include these)
+
+Greetings/social: sure, okay, ok, hi, hello, hey, thanks, yeah, yes, no, well, right, um, uh
+Pronouns/articles: I, my, me, we, our, you, your, he, she, it, they, the, a, an, this, that, these, those
+Auxiliaries/modals: is, are, was, were, be, been, being, can, could, would, should, will, shall, may, might, must, do, does, did, have, has, had
+Prepositions: to, with, for, in, of, on, at, by, from, into, about, through, between, after, before, during
+Conjunctions: and, or, but, so, because, if, when, while, although, since
+Filler/hedging: want, need, help, try, think, know, look, going, trying, looking, basically, actually, really, just, some, also, please, maybe, probably, kind, sort, pretty, very, quite, like
+Generic: code, file, app, stuff, thing, feature, issue, problem, way, part, bit, lot, something
+
+## Bad vs Good Examples
+
+BAD:  sure help refactor code cleanup          -> starts with filler, "code" is generic
+GOOD: refactor database queries connection pooling
+
+BAD:  want add feature authentication          -> "want" is filler, "feature" is noise
+GOOD: add authentication Express JWT middleware
+
+BAD:  looking fix issue login page             -> gerund opener, "issue" is generic
+GOOD: fix login redirect blank page session
+
+BAD:  improve things make better setup         -> vague nouns, no technical specificity
+GOOD: improve CI pipeline GitHub Actions caching
+
+BAD:  help update documentation readme stuff   -> "help" opener, "stuff" is noise
+GOOD: update README API endpoints documentation
+
+BAD:  thinking about maybe changing prompt     -> hedging words, no specificity
+GOOD: optimize context ID extraction prompting Opus
+
+## Output
+
+Output ONLY the keyword tags separated by spaces. Nothing else. No reasoning, no labels, no punctuation, no quotes, no hyphens, no markdown."""
+
+
+def generate_context_id_slug(prompt: str, timeout: int = 3) -> Optional[str]:
+    """
+    Generate a 3-12 word context ID slug from a user prompt using AI inference.
+
+    Uses Haiku (fast tier) for low-latency keyword extraction within hook timeout budgets.
+    Returns a cleaned, validated slug or None on failure.
+
+    Args:
+        prompt: Raw user prompt to extract keywords from
+        timeout: Timeout in seconds (default 3, fits within 5-10s hook budget)
+
+    Returns:
+        Space-separated keyword slug (3-12 words) or None if failed
+    """
+    # Truncate input to 500 chars to keep inference fast
+    truncated = prompt[:500] if len(prompt) > 500 else prompt
+
+    result = inference(
+        system_prompt=CONTEXT_ID_SLUG_PROMPT,
+        user_prompt=truncated,
+        level="fast",
+        timeout=timeout,
+    )
+
+    if not result.success or not result.output:
+        log_warn("inference", f"Context ID slug inference failed: {result.error}")
+        return None
+
+    slug = result.output.strip()
+
+    # Clean: strip quotes, punctuation, hyphens
+    slug = slug.strip('"\'`')
+    slug = slug.rstrip('.!?')
+    slug = slug.replace('-', ' ')
+
+    # Remove non-alphanumeric chars (except spaces)
+    slug = re.sub(r'[^a-zA-Z0-9 ]', '', slug)
+
+    # Normalize whitespace
+    slug = re.sub(r'\s+', ' ', slug).strip()
+
+    words = slug.split()
+
+    # Validate word count: truncate if over 12, reject if under 3
+    if len(words) > 12:
+        words = words[:12]
+    if len(words) < 3:
+        log_debug("inference", f"Context ID slug too short ({len(words)} words): '{slug}'")
+        return None
+
+    result_slug = ' '.join(words)
+    log_debug("inference", f"Generated context ID slug: '{result_slug}' ({result.latency_ms}ms)")
+    return result_slug

package/dist/templates/_shared/lib/base/logger.py

@@ -0,0 +1,291 @@
+"""Unified logging for all hooks and libraries.
+
+Provides a single logging interface that replaces:
+- log_hook_error() from hook_utils.py (error-only, plain text)
+- debug.py from cc-native (per-context, plain text)
+- eprint() for diagnostic output (stderr-only, no persistence)
+
+Log format: JSONL (one JSON object per line)
+Log locations:
+- With context: _output/contexts/<context-id>/debug/hook-log.jsonl
+- Without context (fallback): _output/hook-log.jsonl
+
+Environment variables:
+- HOOK_LOG_DISABLE=1: Disable all file logging
+- HOOK_LOG_LEVEL=warn: Minimum level to log (default: debug)
+- HOOK_ERROR_LOG_DISABLE=1: Legacy alias for HOOK_LOG_DISABLE
+
+Never raises — all errors silently swallowed.
+No buffering — each call is one open+write+close.
+Stdlib only — json, os, sys, datetime, pathlib.
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+_LEVELS = {"debug": 0, "info": 1, "warn": 2, "error": 3}
+
+_MAX_LOG_SIZE = 1024 * 1024  # 1MB
+_TRUNCATE_TO = 512 * 1024    # 512KB
+
+# Module-level context path cache.
+# Set once per hook process via set_context_path() or auto-resolved on first use.
+_cached_context_path: Optional[Path] = None
+_context_resolved: bool = False
+
+
+def set_context_path(path: Optional[Path]) -> None:
+    """Set the context path for this process. All subsequent log calls use it.
+
+    Call this once in your hook after resolving the context:
+        from lib.base.logger import set_context_path
+        set_context_path(get_context_dir(context_id, project_root))
+
+    Args:
+        path: Path to context folder (e.g., _output/contexts/<context-id>/)
+              or None to force global-only logging.
+    """
+    global _cached_context_path, _context_resolved
+    _cached_context_path = path
+    _context_resolved = True
+
+
+def _auto_resolve_context_path() -> Optional[Path]:
+    """Try to auto-resolve context path from session_id. Called once per process.
+
+    Uses the context store to look up which context owns this session,
+    then returns its directory path. Falls back to None (global log).
+    """
+    global _cached_context_path, _context_resolved
+    _context_resolved = True  # Don't retry on failure
+
+    try:
+        from ..context.context_store import get_context_by_session_id
+        from .constants import get_context_dir
+
+        # Hook input isn't available here, but we can check if a recent
+        # context dir exists by scanning _output/contexts/ for one that
+        # has a state.json with a matching session
+        # This is too expensive for a logger. Instead, rely on set_context_path().
+    except Exception:
+        pass
+
+    return None
+
+
+def _get_context_path() -> Optional[Path]:
+    """Get the cached context path, auto-resolving on first call."""
+    global _context_resolved
+    if not _context_resolved:
+        _auto_resolve_context_path()
+    return _cached_context_path
+
+
+def _get_min_level() -> int:
+    """Get minimum log level from environment."""
+    env = os.environ.get("HOOK_LOG_LEVEL", "debug").lower()
+    return _LEVELS.get(env, 0)
+
+
+def _is_disabled() -> bool:
+    """Check if file logging is disabled."""
+    if os.environ.get("HOOK_LOG_DISABLE") == "1":
+        return True
+    if os.environ.get("HOOK_ERROR_LOG_DISABLE") == "1":
+        return True
+    return False
+
+
+def _get_project_root() -> Path:
+    """Get project root from environment or cwd."""
+    env_dir = os.environ.get("CLAUDE_PROJECT_DIR", "")
+    return Path(env_dir) if env_dir else Path.cwd()
+
+
+def hook_log(
+    level: str,
+    hook_name: str,
+    message: str,
+    *,
+    component: str = "",
+    data: Any = None,
+    traceback_str: str = "",
+    context_path: Optional[Path] = None,
+    stderr: bool = True,
+) -> None:
+    """Write a structured log entry.
+
+    Args:
+        level: "debug" | "info" | "warn" | "error"
+        hook_name: Hook or module name (e.g., "session_end")
+        message: Log message
+        component: Sub-component (e.g., "git", "parse")
+        data: Optional structured data (must be JSON-serializable)
+        traceback_str: Optional traceback string
+        context_path: If provided, logs to context debug dir
+        stderr: Also write to stderr (default: True)
+    """
+    try:
+        level_lower = level.lower()
+        level_num = _LEVELS.get(level_lower, 0)
+
+        # Write to stderr if requested
+        if stderr:
+            prefix = f"[{hook_name}]"
+            if component:
+                prefix = f"[{hook_name}:{component}]"
+            print(f"{prefix} {message}", file=sys.stderr)
+            if traceback_str:
+                print(traceback_str, file=sys.stderr)
+
+        # Check if file logging is enabled
+        if _is_disabled():
+            return
+
+        # Check minimum level
+        if level_num < _get_min_level():
+            return
+
+        # Build JSONL entry
+        ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+        entry = {
+            "ts": ts,
+            "level": level_lower,
+            "hook": hook_name,
+            "msg": message,
+        }
+        if component:
+            entry["component"] = component
+        if data is not None:
+            try:
+                json.dumps(data, default=str)  # Validate serializable
+                entry["data"] = data
+            except (TypeError, ValueError):
+                entry["data"] = str(data)
+        if traceback_str:
+            entry["tb"] = traceback_str.rstrip()
+
+        line = json.dumps(entry, ensure_ascii=True, default=str) + "\n"
+
+        # Determine log path: explicit > cached > global
+        resolved_ctx = context_path or _get_context_path()
+        if resolved_ctx and resolved_ctx.exists():
+            log_path = resolved_ctx / "debug" / "hook-log.jsonl"
+        else:
+            project_root = _get_project_root()
+            log_path = project_root / "_output" / "hook-log.jsonl"
+
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Size guard (global log only, not per-context)
+        if not resolved_ctx and log_path.exists():
+            try:
+                if log_path.stat().st_size > _MAX_LOG_SIZE:
+                    file_data = log_path.read_bytes()
+                    log_path.write_bytes(file_data[-_TRUNCATE_TO:])
+            except OSError:
+                pass
+
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(line)
+
+    except Exception:
+        pass  # Never crash
+
+
+def log_debug(hook_name: str, message: str, **kwargs: Any) -> None:
+    """Log a debug-level message."""
+    hook_log("debug", hook_name, message, **kwargs)
+
+
+def log_info(hook_name: str, message: str, **kwargs: Any) -> None:
+    """Log an info-level message."""
+    hook_log("info", hook_name, message, **kwargs)
+
+
+def log_warn(hook_name: str, message: str, **kwargs: Any) -> None:
+    """Log a warn-level message."""
+    hook_log("warn", hook_name, message, **kwargs)
+
+
+def log_error(hook_name: str, message: str, **kwargs: Any) -> None:
+    """Log an error-level message."""
+    hook_log("error", hook_name, message, **kwargs)
+
+
+def log_diagnostic(
+    hook_name: str,
+    phase: str,
+    summary: str,
+    *,
+    inputs: Any = None,
+    decision: Any = None,
+    reasoning: Any = None,
+    component: str = "diag",
+    data: Any = None,
+) -> None:
+    """Log a structured diagnostic entry at a hook decision point.
+
+    Emits a debug-level JSONL entry with tagged, filterable data.
+    Use at key decision points: receive (what came in), decide (what was chosen),
+    result (what happened).
+
+    Args:
+        hook_name: Hook or module name (e.g., "session_start")
+        phase: Decision phase — "receive", "decide", or "result"
+        summary: One-line description (e.g., "source=clear, session=a1b2c3d4")
+        inputs: Input data relevant to this phase
+        decision: The decision made (for "decide" phase)
+        reasoning: Why this decision was made
+        component: Log component tag (default: "diag")
+        data: Extra data to merge into the structured entry
+    """
+    diag_data: Dict[str, Any] = {"phase": phase}
+    if inputs is not None:
+        diag_data["inputs"] = inputs
+    if decision is not None:
+        diag_data["decision"] = decision
+    if reasoning is not None:
+        diag_data["reasoning"] = reasoning
+    if data is not None and isinstance(data, dict):
+        diag_data.update(data)
+    hook_log(
+        "debug",
+        hook_name,
+        f"[DIAG:{phase}] {summary}",
+        component=component,
+        data=diag_data,
+    )
+
+
+def log_hook_error(
+    hook_name: str,
+    error: Exception,
+    hook_event: str = "unknown",
+    traceback_str: str = "",
+) -> None:
+    """Backward-compatible wrapper matching the old hook_utils.log_hook_error signature.
+
+    Delegates to hook_log("error", ...) with the same behavior:
+    - Message capped at 200 chars, newlines stripped
+    - Never raises
+
+    Args:
+        hook_name: Name of the hook
+        error: The exception that occurred
+        hook_event: Hook event type (e.g., "PreToolUse")
+        traceback_str: Optional formatted traceback
+    """
+    msg = str(error).replace("\n", " ").replace("\r", "")[:200]
+    err_type = type(error).__name__
+    hook_log(
+        "error",
+        hook_name,
+        f"[{hook_event}] {err_type}: {msg}",
+        traceback_str=traceback_str,
+        stderr=True,
+    )