claude-smart 0.2.30 → 0.2.32

package/plugin/src/claude_smart/env_config.py

@@ -0,0 +1,102 @@
+"""Shared ``~/.reflexio/.env`` helpers for claude-smart."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+REFLEXIO_ENV_PATH = Path.home() / ".reflexio" / ".env"
+MANAGED_REFLEXIO_URL = "https://www.reflexio.ai/"
+REFLEXIO_URL_ENV = "REFLEXIO_URL"
+REFLEXIO_API_KEY_ENV = "REFLEXIO_API_KEY"
+
+
+def parse_env_line(line: str) -> tuple[str, str] | None:
+    """Parse a simple dotenv ``KEY=value`` line.
+
+    This intentionally ignores comments, blank lines, and shell features. The
+    Reflexio env writer emits plain quoted assignments, which is all
+    claude-smart needs here.
+    """
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if stripped.startswith("export "):
+        stripped = stripped[len("export ") :].lstrip()
+    key, sep, raw_value = stripped.partition("=")
+    if not sep:
+        return None
+    key = key.strip()
+    if not key or not key.replace("_", "").isalnum() or key[0].isdigit():
+        return None
+    value = raw_value.strip()
+    if len(value) >= 2 and (
+        (value[0] == value[-1] == '"') or (value[0] == value[-1] == "'")
+    ):
+        value = value[1:-1]
+    return key, value
+
+
+def load_reflexio_env(path: Path | None = None) -> None:
+    """Load ``~/.reflexio/.env`` into ``os.environ`` without overriding values."""
+    path = path or REFLEXIO_ENV_PATH
+    try:
+        text = path.read_text()
+    except OSError:
+        return
+    for line in text.splitlines():
+        parsed = parse_env_line(line)
+        if parsed is None:
+            continue
+        key, value = parsed
+        os.environ.setdefault(key, value)
+
+
+def set_env_vars(path: Path, values: dict[str, str]) -> list[str]:
+    """Upsert dotenv keys while preserving comments and unrelated entries."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        existing = path.read_text()
+    except OSError:
+        existing = ""
+
+    lines = existing.splitlines()
+    seen: set[str] = set()
+    out: list[str] = []
+    for line in lines:
+        parsed = parse_env_line(line)
+        if parsed is None:
+            out.append(line)
+            continue
+        key, _old = parsed
+        if key in values:
+            out.append(f'{key}="{_escape_env_value(values[key])}"')
+            seen.add(key)
+        else:
+            out.append(line)
+
+    added: list[str] = []
+    for key, value in values.items():
+        if key in seen:
+            continue
+        out.append(f'{key}="{_escape_env_value(value)}"')
+        added.append(key)
+
+    content = "\n".join(out)
+    path.write_text(content + ("\n" if content else ""), encoding="utf-8")
+    path.chmod(0o600)
+    return added
+
+
+def mask_secret(value: str) -> str:
+    """Return a display-safe API key preview."""
+    if not value:
+        return ""
+    if len(value) <= 8:
+        return "*" * len(value)
+    prefix = value[:5] if "-" in value[:8] else value[:4]
+    return f"{prefix}****{value[-4:]}"
+
+
+def _escape_env_value(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')

package/plugin/src/claude_smart/events/session_end.py

@@ -1,20 +1,185 @@
-"""SessionEnd hook — flush any remaining interactions; extraction runs async."""
+"""SessionEnd hook — flush any remaining interactions; extraction runs async.
+
+When ``Stop`` never fires during a session (autonomous agentic loops
+that don't reach ``stop_reason=end_turn``), the buffer at SessionEnd
+time can contain orphan ``Assistant_tool`` records with no closing
+``Assistant`` anchor. The ``state.unpublished_slice`` contract folds
+tool records into the *next* Assistant turn's ``tools_used``; without
+that anchor, every buffered tool call is silently dropped at publish
+time and reflexio receives only the original User prompt.
+
+This module synthesises a closing Assistant record from whatever
+assistant text the Claude Code transcript still has, so the publish
+carries the full tool record stream instead of just the User prompt.
+A short placeholder string is used when the transcript is unreadable.
+"""
 
 from __future__ import annotations
 
+import logging
+import time
+from pathlib import Path
 from typing import Any
 
-from claude_smart import ids, publish
+from claude_smart import ids, publish, state
+from claude_smart.events.stop import (
+    _read_transcript_entries,
+    _scan_transcript_for_assistant_text,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# Fallback Assistant content used when the transcript is missing,
+# unreadable, or has no recoverable assistant text. The string is
+# distinctive so a future audit can grep for it and quantify how often
+# a session ended without any model response.
+_PLACEHOLDER_ASSISTANT_TEXT = "<session ended without final assistant response>"
 
 
-def handle(payload: dict[str, Any]) -> None:
+def handle(payload: dict[str, Any]) -> tuple[publish.PublishStatus, int] | None:
+    """Flush any remaining buffered turns to reflexio.
+
+    Args:
+        payload (dict[str, Any]): Claude Code hook payload.
+
+    Returns:
+        tuple[PublishStatus, int] | None: The ``(status, count)`` tuple
+            from ``publish.publish_unpublished`` so the dispatcher's
+            forensic hook log captures the publish outcome. ``None``
+            when the payload had no ``session_id``.
+    """
     session_id = payload.get("session_id")
     if not session_id:
-        return
+        return None
     project_id = ids.resolve_project_id(payload.get("cwd"))
-    publish.publish_unpublished(
+
+    _maybe_synthesize_assistant_anchor(
         session_id=session_id,
         project_id=project_id,
-        force_extraction=False,
+        transcript_path=payload.get("transcript_path"),
+    )
+
+    # ``force_extraction=True`` makes the reflexio server run the
+    # extractor synchronously for this publish, so by the time the HTTP
+    # call returns the playbook (if any) is already committed. SessionEnd
+    # is the final flush — the user/agent is already going away — so
+    # adding a few extra seconds here trades nothing for "snapshot_playbooks()
+    # reads after this point see the just-extracted rows." Stop hooks
+    # (the per-turn flushes) stay async so they don't slow interactive
+    # generation.
+    return publish.publish_unpublished(
+        session_id=session_id,
+        project_id=project_id,
+        force_extraction=True,
         skip_aggregation=False,
     )
+
+
+def _maybe_synthesize_assistant_anchor(
+    *,
+    session_id: str,
+    project_id: str,
+    transcript_path: Any,
+) -> None:
+    """Append a closing Assistant record when the unpublished tail
+    holds orphan ``Assistant_tool`` rows.
+
+    Walks the post-watermark slice of the buffer and looks for a tail
+    pattern of ``Assistant_tool`` records that aren't followed by an
+    ``Assistant`` record. If that's the case, scans the Claude Code
+    transcript for whatever final assistant text is recoverable and
+    appends one synthetic ``Assistant`` record so
+    ``state.unpublished_slice`` can fold the tools into its
+    ``tools_used`` field at publish time.
+
+    Args:
+        session_id (str): Claude Code session id for the state buffer.
+        project_id (str): Resolved project_id used as the synthetic
+            record's ``user_id`` (matches Stop's convention).
+        transcript_path (Any): The ``transcript_path`` value from the
+            hook payload — accepted as ``Any`` because Claude Code may
+            send a string, ``None``, or omit the key entirely.
+
+    Returns:
+        None
+    """
+    records = state.read_all(session_id)
+    if not _tail_has_orphan_tools(records):
+        return
+
+    assistant_text = _recover_assistant_text(transcript_path)
+    state.append(
+        session_id,
+        {
+            "ts": int(time.time()),
+            "role": "Assistant",
+            "content": assistant_text,
+            "user_id": project_id,
+            "synthesised_by": "session_end_anchor",
+        },
+    )
+    _LOGGER.info(
+        "session_end: synthesised Assistant anchor for %s (len=%d)",
+        session_id,
+        len(assistant_text),
+    )
+
+
+def _tail_has_orphan_tools(records: list[dict[str, Any]]) -> bool:
+    """Return True when the post-watermark tail ends with one or more
+    ``Assistant_tool`` records with no closing ``Assistant`` record.
+
+    Walks records from the latest ``published_up_to`` marker forward;
+    tracks the most recent record role. The tail is considered "orphan"
+    when at least one ``Assistant_tool`` was seen after the watermark
+    and no ``Assistant`` record was seen *after* the last
+    ``Assistant_tool``.
+
+    Args:
+        records (list[dict[str, Any]]): The full buffered record list
+            as returned by ``state.read_all``.
+
+    Returns:
+        bool: True if a synthetic anchor would unblock publishing tool
+            records that would otherwise be dropped.
+    """
+    # Find the most recent published_up_to watermark.
+    published = 0
+    for rec in records:
+        if "published_up_to" in rec:
+            published = rec["published_up_to"]
+
+    tail = records[published:]
+    saw_orphan_tool = False
+    for rec in tail:
+        role = rec.get("role")
+        if role == "Assistant_tool":
+            saw_orphan_tool = True
+        elif role == "Assistant":
+            saw_orphan_tool = False
+    return saw_orphan_tool
+
+
+def _recover_assistant_text(transcript_path: Any) -> str:
+    """Return whatever assistant text the transcript still has, or a placeholder.
+
+    Args:
+        transcript_path (Any): Raw value from the hook payload.
+
+    Returns:
+        str: Concatenated current-turn assistant text from the
+            transcript, or ``_PLACEHOLDER_ASSISTANT_TEXT`` when the
+            transcript is unset, missing, or yields nothing.
+    """
+    if not isinstance(transcript_path, str) or not transcript_path:
+        return _PLACEHOLDER_ASSISTANT_TEXT
+    path = Path(transcript_path)
+    if not path.is_file():
+        return _PLACEHOLDER_ASSISTANT_TEXT
+    try:
+        entries = _read_transcript_entries(path)
+    except OSError as exc:
+        _LOGGER.debug("session_end transcript read failed: %s", exc)
+        return _PLACEHOLDER_ASSISTANT_TEXT
+    text = _scan_transcript_for_assistant_text(entries)
+    return text or _PLACEHOLDER_ASSISTANT_TEXT

package/plugin/src/claude_smart/events/session_start.py

@@ -15,8 +15,32 @@ from claude_smart.stall_banner import render_banner
 # Claude-smart's preferred extraction cadence — more frequent, smaller windows
 # than reflexio's out-of-box 10/5. Applied idempotently to the reflexio server
 # on every SessionStart via Adapter.apply_extraction_defaults.
-_CLAUDE_SMART_WINDOW_SIZE = 5
-_CLAUDE_SMART_STRIDE_SIZE = 3
+#
+# Env-var overrides let benchmark harnesses (SWE-bench Verified, in particular)
+# run with ``CLAUDE_SMART_STRIDE_SIZE=1`` so a single short autonomous session
+# triggers extraction on its sole publish instead of being silently filtered
+# out by the stride pre-filter (``new < stride_size``). Production users keep
+# the defaults; the values are only read on SessionStart, so a launcher that
+# sets the env var has predictable effect for the entire Claude Code session.
+#
+# Parsing is defensive: a non-integer env value falls back to the default
+# rather than raising at import time. SessionStart is the hook that wires up
+# every subsequent hook, so an import-time crash here would silently disable
+# the whole plugin for the session.
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+_CLAUDE_SMART_WINDOW_SIZE = _int_env("CLAUDE_SMART_WINDOW_SIZE", 5)
+_CLAUDE_SMART_STRIDE_SIZE = _int_env("CLAUDE_SMART_STRIDE_SIZE", 3)
 # Optimizer is on by default. Set this env var to "0" to skip pushing the
 # claude-smart optimizer defaults on SessionStart (kill switch).
 _DISABLE_OPTIMIZER_ENV = "CLAUDE_SMART_ENABLE_OPTIMIZER"

package/plugin/src/claude_smart/events/stop.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import time
 from pathlib import Path
 from typing import Any
@@ -289,7 +290,7 @@ def _resolve_cited_items(session_id: str, cited_ids: list[str]) -> list[dict[str
     for cid in cited_ids:
         if cid in seen:
             continue
-        entry = registry.get(cid)
+        entry = _registry_entry_for_citation(registry, cid)
         if not entry:
             continue
         seen.add(cid)
@@ -308,10 +309,44 @@ def _resolve_cited_items(session_id: str, cited_ids: list[str]) -> list[dict[str
     return resolved
 
 
-def handle(payload: dict[str, Any]) -> None:
+def _registry_entry_for_citation(
+    registry: dict[str, dict[str, Any]], citation: str
+) -> dict[str, Any] | None:
+    """Resolve a legacy rank id or a dashboard-route citation token."""
+    if not citation.startswith("route:"):
+        return registry.get(citation)
+    try:
+        _, kind, source_kind, real_id = citation.split(":", 3)
+    except ValueError:
+        return None
+    for entry in registry.values():
+        if entry.get("kind") != kind:
+            continue
+        if str(entry.get("real_id") or "") != real_id:
+            continue
+        if kind == "playbook" and entry.get("source_kind") != source_kind:
+            continue
+        return entry
+    return None
+
+
+def handle(payload: dict[str, Any]) -> tuple[publish.PublishStatus, int] | None:
+    """Drain the buffered assistant turn to reflexio.
+
+    Args:
+        payload (dict[str, Any]): Claude Code hook payload.
+
+    Returns:
+        tuple[PublishStatus, int] | None: The ``(status, count)`` tuple
+            from ``publish.publish_unpublished`` so the dispatcher can
+            include it in the forensic hook log. ``None`` is returned
+            only when the handler short-circuits before publishing (no
+            ``session_id`` in the payload, or Codex internal-prompt
+            detection skipped the fire).
+    """
     session_id = payload.get("session_id")
     if not session_id:
-        return
+        return None
 
     # Always append an Assistant record, even when the turn emitted only
     # tool calls and no text. ``state.unpublished_slice`` folds any
@@ -330,9 +365,8 @@ def handle(payload: dict[str, Any]) -> None:
     prompt = payload.get("prompt") or (
         _scan_transcript_for_user_text(entries) if runtime.is_codex() else ""
     )
-    if runtime.is_codex():
-        if internal_call.is_codex_internal_prompt(prompt):
-            return
+    if runtime.is_codex() and internal_call.is_codex_internal_prompt(prompt):
+        return None
 
     last_assistant_message = payload.get("last_assistant_message")
     assistant_text = (
@@ -344,11 +378,16 @@ def handle(payload: dict[str, Any]) -> None:
     )
     if (
         runtime.is_codex()
-        and internal_call.is_codex_title_response(assistant_text)
+        and (
+            internal_call.is_codex_title_response(assistant_text)
+            or internal_call.is_codex_suggestions_response(assistant_text)
+        )
         and not prompt
         and not _has_unpublished_user_turn(session_id)
     ):
-        return
+        return None
+    if os.environ.get("CLAUDE_SMART_CITATIONS", "on") == "off":
+        assistant_text = cs_cite.strip_marker_lines(assistant_text)
     text_cited_ids = cs_cite.parse_text_citations(assistant_text)
     cited_items = _resolve_cited_items(session_id, text_cited_ids)
     plan_decisions = _scan_transcript_for_plan_decisions(entries)
@@ -374,7 +413,7 @@ def handle(payload: dict[str, Any]) -> None:
     if cited_items:
         record["cited_items"] = cited_items
     state.append(session_id, record)
-    publish.publish_unpublished(
+    return publish.publish_unpublished(
         session_id=session_id,
         project_id=project_id,
         force_extraction=False,

package/plugin/src/claude_smart/hook.py

@@ -5,6 +5,13 @@ The plugin's ``hook_entry.sh`` calls either
 ``python -m claude_smart.hook <host> <event>`` once per hook invocation.
 This module reads the hook JSON from stdin, routes to the matching handler,
 and makes sure no unhandled exception ever propagates.
+
+Every fire produces one structured JSON line in
+``~/.claude-smart/hook.log`` via ``hook_log.log_event`` — covers the
+event name, session id, internal-invocation skip, handler outcome
+(``ok`` / ``raised:<Exc>`` / ``unknown_event``), and for Stop/SessionEnd
+the publish status + count. The log is the forensic trail for chasing
+"hook didn't publish" mysteries from a single file.
 """
 
 from __future__ import annotations
@@ -12,15 +19,22 @@ from __future__ import annotations
 import json
 import logging
 import sys
-from typing import Any, Callable
+from collections.abc import Callable
+from contextlib import redirect_stdout
+from io import StringIO
+from typing import Any
 
-from claude_smart import runtime
+from claude_smart import hook_log, ids, runtime
 from claude_smart.internal_call import is_internal_invocation
 
 _LOGGER = logging.getLogger(__name__)
 
 
-def _load_handlers() -> dict[str, Callable[[dict[str, Any]], None]]:
+# Stop and SessionEnd return ``(PublishStatus, int)`` so the dispatcher can
+# log the publish outcome; the other handlers return ``None`` (or nothing).
+# Use ``Any`` here rather than two specialised typedefs — the dispatcher
+# narrows at the call site via ``isinstance(result, tuple)``.
+def _load_handlers() -> dict[str, Callable[[dict[str, Any]], Any]]:
     from claude_smart.events import (
         post_tool,
         pre_tool,
@@ -92,6 +106,15 @@ def main(argv: list[str] | None = None) -> int:
     # handlers so we don't publish the extractor's system prompt back
     # into reflexio. See claude_smart.internal_call for detection logic.
     if is_internal_invocation(payload):
+        hook_log.log_event(
+            event=event,
+            host=host,
+            session_id=payload.get("session_id"),
+            project_id=ids.resolve_project_id(payload.get("cwd")),
+            cwd=payload.get("cwd"),
+            internal_skipped=True,
+            handler_status="ok",
+        )
         emit_continue()
         return 0
 
@@ -99,14 +122,49 @@ def main(argv: list[str] | None = None) -> int:
     handler = handlers.get(event)
     if handler is None:
         _LOGGER.warning("unknown hook event: %s", event)
+        hook_log.log_event(
+            event=event,
+            host=host,
+            session_id=payload.get("session_id"),
+            project_id=ids.resolve_project_id(payload.get("cwd")),
+            cwd=payload.get("cwd"),
+            handler_status="unknown_event",
+        )
         emit_continue()
         return 0
 
+    handler_status = "ok"
+    publish_status: str | None = None
+    publish_count: int | None = None
+    handler_stdout = StringIO()
     try:
-        handler(payload)
+        with redirect_stdout(handler_stdout):
+            result = handler(payload)
+        if isinstance(result, tuple) and len(result) == 2:
+            publish_status, publish_count = result
     except Exception as exc:  # noqa: BLE001 — hooks must never crash the session.
         _LOGGER.exception("hook handler %s raised: %s", event, exc)
+        handler_status = f"raised:{type(exc).__name__}: {exc}"
         emit_continue()
+    else:
+        # Handlers that inject context already emit the full hook JSON. Silent
+        # handlers still need the continue response so the parent session does
+        # not wait on an empty stdout payload.
+        captured = handler_stdout.getvalue()
+        if captured.strip():
+            sys.stdout.write(captured)
+        else:
+            emit_continue()
+    hook_log.log_event(
+        event=event,
+        host=host,
+        session_id=payload.get("session_id"),
+        project_id=ids.resolve_project_id(payload.get("cwd")),
+        cwd=payload.get("cwd"),
+        handler_status=handler_status,
+        publish_status=publish_status,
+        publish_count=publish_count,
+    )
     return 0