claude-smart 0.2.30 → 0.2.31

package/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
   </a>
   <a href="plugin/pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.2.30-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.2.31-green.svg" alt="Version">
   </a>
   <a href="plugin/pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.12-brightgreen.svg" alt="Python">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Self-improving Claude Code plugin — learns from corrections via reflexio",
   "keywords": [
     "claude",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Self-improving Claude Code plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-smart",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Self-improving coding assistant plugin — learns from corrections across sessions via reflexio",
   "author": {
     "name": "Yi Lu"

package/plugin/hooks/hooks.json

@@ -102,7 +102,7 @@
           {
             "type": "command",
             "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/reflexioai/plugin\"; bash \"$_R/scripts/hook_entry.sh\" claude-code session-end",
-            "timeout": 60
+            "timeout": 300
           },
           {
             "type": "command",

package/plugin/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-smart"
-version = "0.2.30"
+version = "0.2.31"
 description = "Self-improving Claude Code plugin — learns from corrections via reflexio"
 readme = "README.md"
 requires-python = ">=3.12"

package/plugin/scripts/_lib.sh

@@ -32,6 +32,16 @@ claude_smart_prepend_node_bins() {
   export PATH="$_CS_NODE_ROOT/bin:$_CS_NODE_ROOT:$PATH"
 }
 
+claude_smart_is_internal_invocation_env() {
+  if [ "${CLAUDE_SMART_INTERNAL:-}" = "1" ]; then
+    return 0
+  fi
+  if [ -n "${CLAUDE_CODE_ENTRYPOINT:-}" ] && [ "${CLAUDE_CODE_ENTRYPOINT:-}" != "cli" ]; then
+    return 0
+  fi
+  return 1
+}
+
 claude_smart_dashboard_unavailable_marker() {
   printf '%s\n' "$HOME/.claude-smart/dashboard-unavailable"
 }
@@ -196,6 +206,61 @@ PY
   return 1
 }
 
+# Print a short fingerprint line for a file ("<cksum>:<size>" or "missing").
+claude_smart_fingerprint_file() {
+  local path
+  path="$1"
+  if [ -f "$path" ]; then
+    cksum "$path" 2>/dev/null | awk '{print $1 ":" $2}'
+  else
+    printf 'missing\n'
+  fi
+}
+
+# Print a multi-line fingerprint covering every input that determines
+# whether smart-install.sh can succeed. Order is stable so the hash is
+# reproducible. Args: $1 = plugin_root, $2 = scripts_dir.
+claude_smart_install_fingerprint() {
+  local plugin_root script_dir
+  plugin_root="$1"
+  script_dir="$2"
+  printf 'plugin_root=%s\n' "$plugin_root"
+  printf 'smart_install=%s\n' "$(claude_smart_fingerprint_file "$script_dir/smart-install.sh")"
+  printf 'lib=%s\n' "$(claude_smart_fingerprint_file "$script_dir/_lib.sh")"
+  printf 'pyproject=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/pyproject.toml")"
+  printf 'uv_lock=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/uv.lock")"
+  # Resolved python interpreter — catches a system upgrade (3.12.4 → 3.12.5)
+  # that would otherwise let install_complete return true against a venv
+  # built against a now-deleted interpreter.
+  if command -v uv >/dev/null 2>&1; then
+    printf 'python=%s\n' "$(uv python find 3.12 2>/dev/null || echo missing)"
+  else
+    printf 'python=no-uv\n'
+  fi
+  if [ -d "$plugin_root/dashboard" ]; then
+    printf 'dashboard_pkg=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/dashboard/package.json")"
+    printf 'dashboard_lock=%s\n' "$(claude_smart_fingerprint_file "$plugin_root/dashboard/package-lock.json")"
+  else
+    printf 'dashboard_pkg=none\n'
+    printf 'dashboard_lock=none\n'
+  fi
+}
+
+# Hash the install fingerprint to a single short hex string. Used by the
+# install-failed marker so hook_entry.sh can detect when inputs change and
+# auto-clear a stale marker. Args: $1 = plugin_root, $2 = scripts_dir.
+claude_smart_install_fingerprint_hash() {
+  local plugin_root script_dir tmp rc
+  plugin_root="$1"
+  script_dir="$2"
+  tmp=$(mktemp 2>/dev/null) || return 1
+  claude_smart_install_fingerprint "$plugin_root" "$script_dir" > "$tmp"
+  claude_smart_sha256_file "$tmp"
+  rc=$?
+  rm -f "$tmp"
+  return $rc
+}
+
 # Return 0 if `node` exists and satisfies the minimum major/minor pair.
 # Patch versions are intentionally ignored because our requirement is a
 # floor, not an exact runtime pin.

package/plugin/scripts/backend-service.sh

@@ -25,15 +25,21 @@ claude_smart_prepend_astral_bins
 
 CMD="${1:-start}"
 PORT=8071
+EMBEDDING_PORT="${EMBEDDING_PORT:-8072}"
 # Pass through to `reflexio services start/stop` so the spawned backend
 # binds to PORT instead of reflexio's library default (8081).
 export BACKEND_PORT="$PORT"
+export EMBEDDING_PORT
 
 # Default: route extraction through the active host CLI + ONNX embedder
 # so claude-smart works without any LLM API key. Users can opt out by
 # pre-exporting these to 0.
 export CLAUDE_SMART_USE_LOCAL_CLI="${CLAUDE_SMART_USE_LOCAL_CLI:-1}"
 export CLAUDE_SMART_USE_LOCAL_EMBEDDING="${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-1}"
+if [ "${CLAUDE_SMART_USE_LOCAL_EMBEDDING:-}" = "1" ]; then
+  export REFLEXIO_EMBEDDING_PROVIDER="${REFLEXIO_EMBEDDING_PROVIDER:-local_service}"
+  export REFLEXIO_EMBEDDING_SERVICE_URL="${REFLEXIO_EMBEDDING_SERVICE_URL:-http://127.0.0.1:$EMBEDDING_PORT}"
+fi
 # The backend can be spawned from contexts whose PATH lacks the host
 # CLI dir (commonly ~/.local/bin or /opt/homebrew/bin). Pin the CLI
 # explicitly if we can resolve it from our own (post-login-path) PATH.
@@ -173,6 +179,9 @@ full_stop() {
 
 case "$CMD" in
   start)
+    if claude_smart_is_internal_invocation_env; then
+      emit_ok; exit 0
+    fi
     # Opt-out: users who don't want the backend managed by the hook can
     # set CLAUDE_SMART_BACKEND_AUTOSTART=0.
     if [ "${CLAUDE_SMART_BACKEND_AUTOSTART:-1}" = "0" ]; then
@@ -206,16 +215,21 @@ case "$CMD" in
     export INTERACTION_CLEANUP_THRESHOLD="${INTERACTION_CLEANUP_THRESHOLD:-500}"
     export INTERACTION_CLEANUP_DELETE_COUNT="${INTERACTION_CLEANUP_DELETE_COUNT:-200}"
 
-    # --no-reload: uvicorn's reloader forks a supervisor; makes
-    # bookkeeping harder and we don't need hot-reload for a user-facing
-    # service. Detach via claude_smart_spawn_detached so the same code
-    # path covers Linux (setsid), macOS (python3 os.setsid), and Windows
     # (nohup; no process groups). backend-log-runner.sh owns stdout/stderr
     # capture so process output cannot grow backend.log past its cap.
+    #
+    # --workers: reflexio defaults to 2 (zero-downtime worker recycling
+    # for server deployments). For a single-user Claude Code plugin
+    # that's pure overhead: ~1.1 GB extra RSS, periodic 5–10 s spawn
+    # hiccups during worker rotation, and SQLite can't accept concurrent
+    # writers anyway. Default to 1 here; opt in to N via
+    # CLAUDE_SMART_BACKEND_WORKERS for power users running concurrent
+    # Claude Code sessions or wanting zero-downtime recycling.
+    workers="${CLAUDE_SMART_BACKEND_WORKERS:-1}"
     claude_smart_spawn_detached bash "$HERE/backend-log-runner.sh" \
       "$LOG_FILE" "$LOG_MAX_BYTES" -- \
       uv run --project "$PLUGIN_ROOT" --quiet \
-      reflexio services start --only backend --no-reload
+      reflexio services start --only backend --no-reload --workers "$workers"
     svc_pid=$!
     # Record the spawned pid, not a pgid sampled with ps. On POSIX,
     # setsid/python os.setsid make this pid the new process group leader;

package/plugin/scripts/cli.sh

@@ -24,7 +24,7 @@ PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 # on a broken install.
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
 if [ -f "$FAILURE_MARKER" ]; then
-  msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "")"
+  msg="$(head -n 1 "$FAILURE_MARKER" 2>/dev/null || echo "")"
   [ -n "$msg" ] || msg="unknown error"
   echo "claude-smart is not installed correctly: $msg" >&2
   echo "Re-run the plugin's Setup (restart Claude Code) or fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
@@ -50,7 +50,8 @@ if ! command -v uv >/dev/null 2>&1; then
   fi
   if ! command -v uv >/dev/null 2>&1; then
     if [ -f "$FAILURE_MARKER" ]; then
-      msg="$(cat "$FAILURE_MARKER" 2>/dev/null || echo "unknown error")"
+      msg="$(head -n 1 "$FAILURE_MARKER" 2>/dev/null || echo "")"
+      [ -n "$msg" ] || msg="unknown error"
       echo "claude-smart: install failed: $msg" >&2
       echo "Fix the underlying issue and delete $FAILURE_MARKER to retry." >&2
     else

package/plugin/scripts/dashboard-service.sh

@@ -87,6 +87,9 @@ port_occupied() {
 
 case "$CMD" in
   start)
+    if claude_smart_is_internal_invocation_env; then
+      emit_ok; exit 0
+    fi
     # Opt-out: users who don't want the dashboard long-lived can set
     # CLAUDE_SMART_DASHBOARD_AUTOSTART=0 in their environment.
     if [ "${CLAUDE_SMART_DASHBOARD_AUTOSTART:-1}" = "0" ]; then

package/plugin/scripts/hook_entry.sh

@@ -26,6 +26,10 @@ fi
 HERE="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=_lib.sh
 . "$HERE/_lib.sh"
+if claude_smart_is_internal_invocation_env; then
+  echo '{"continue":true,"suppressOutput":true}'
+  exit 0
+fi
 # Pick up uv from the user's login-shell PATH (covers ~/.local/bin populated
 # by the astral.sh installer) so a fresh install works before the user
 # restarts their terminal. Matches the pattern used by smart-install.sh.
@@ -39,10 +43,20 @@ PLUGIN_ROOT="$(cd "$HERE/.." && pwd)"
 FAILURE_MARKER="$HOME/.claude-smart/install-failed"
 STATE_DIR="$HOME/.claude-smart"
 if [ -f "$FAILURE_MARKER" ]; then
-  if [ "$EVENT" = "session-start" ] && command -v python3 >/dev/null 2>&1; then
-    python3 - "$FAILURE_MARKER" <<'PY'
+  # Auto-clear the marker when install inputs have changed since the
+  # failure was recorded (pyproject.toml / uv.lock / smart-install.sh /
+  # python interpreter etc.). Without this the plugin stays muted forever
+  # after a transient sync failure even when the user has fixed it.
+  stored_fp="$(awk -F= '$1=="fingerprint"{print $2; exit}' "$FAILURE_MARKER" 2>/dev/null || true)"
+  current_fp="$(claude_smart_install_fingerprint_hash "$PLUGIN_ROOT" "$HERE" 2>/dev/null || true)"
+  if [ -z "$stored_fp" ] || [ "$stored_fp" != "$current_fp" ]; then
+    rm -f "$FAILURE_MARKER"
+  else
+    if [ "$EVENT" = "session-start" ] && command -v python3 >/dev/null 2>&1; then
+      python3 - "$FAILURE_MARKER" <<'PY'
 import json, pathlib, sys
-msg = pathlib.Path(sys.argv[1]).read_text().strip() or "unknown error"
+first = pathlib.Path(sys.argv[1]).read_text().splitlines()
+msg = (first[0].strip() if first else "") or "unknown error"
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",
@@ -55,10 +69,11 @@ print(json.dumps({
     }
 }))
 PY
-  else
-    echo '{"continue":true,"suppressOutput":true}'
+    else
+      echo '{"continue":true,"suppressOutput":true}'
+    fi
+    exit 0
   fi
-  exit 0
 fi
 
 if ! command -v uv >/dev/null 2>&1; then

package/plugin/scripts/smart-install.sh

@@ -80,45 +80,23 @@ acquire_install_lock
 rm -f "$FAILURE_MARKER"
 
 write_failure() {
-  local reason
+  local reason fp_hash
   reason="$1"
-  printf '%s\n' "$reason" > "$FAILURE_MARKER"
+  fp_hash="$(claude_smart_install_fingerprint_hash "$PLUGIN_ROOT" "$HERE" 2>/dev/null || true)"
+  {
+    printf '%s\n' "$reason"
+    if [ -n "$fp_hash" ]; then
+      printf 'fingerprint=%s\n' "$fp_hash"
+    fi
+  } > "$FAILURE_MARKER"
   rm -f "$SUCCESS_MARKER"
   echo "[claude-smart] install failed: $reason" >&2
   echo '{"continue":true,"suppressOutput":true}'
   exit 0
 }
 
-fingerprint_file() {
-  local path
-  path="$1"
-  if [ -f "$path" ]; then
-    cksum "$path" 2>/dev/null | awk '{print $1 ":" $2}'
-  else
-    printf 'missing\n'
-  fi
-}
-
 install_fingerprint() {
-  printf 'plugin_root=%s\n' "$PLUGIN_ROOT"
-  printf 'smart_install=%s\n' "$(fingerprint_file "$HERE/smart-install.sh")"
-  printf 'pyproject=%s\n' "$(fingerprint_file "$PLUGIN_ROOT/pyproject.toml")"
-  printf 'uv_lock=%s\n' "$(fingerprint_file "$PLUGIN_ROOT/uv.lock")"
-  # Resolved python interpreter — catches a system upgrade (3.12.4 → 3.12.5)
-  # that would otherwise let install_complete return true against a venv
-  # built against a now-deleted interpreter.
-  if command -v uv >/dev/null 2>&1; then
-    printf 'python=%s\n' "$(uv python find 3.12 2>/dev/null || echo missing)"
-  else
-    printf 'python=no-uv\n'
-  fi
-  if [ -d "$PLUGIN_ROOT/dashboard" ]; then
-    printf 'dashboard_pkg=%s\n' "$(fingerprint_file "$PLUGIN_ROOT/dashboard/package.json")"
-    printf 'dashboard_lock=%s\n' "$(fingerprint_file "$PLUGIN_ROOT/dashboard/package-lock.json")"
-  else
-    printf 'dashboard_pkg=none\n'
-    printf 'dashboard_lock=none\n'
-  fi
+  claude_smart_install_fingerprint "$PLUGIN_ROOT" "$HERE"
 }
 
 install_complete() {

package/plugin/src/claude_smart/cli.py

@@ -205,7 +205,8 @@ def _bootstrap_claude_code_install() -> tuple[bool, str]:
     if result.returncode != 0:
         return False, f"smart-install.sh failed in {plugin_root}"
     if _INSTALL_FAILURE_MARKER.is_file():
-        reason = _INSTALL_FAILURE_MARKER.read_text().strip() or "unknown error"
+        first_line = _INSTALL_FAILURE_MARKER.read_text().splitlines()
+        reason = (first_line[0].strip() if first_line else "") or "unknown error"
         return False, reason
     return True, str(plugin_root)
 
@@ -1561,6 +1562,104 @@ def cmd_clear_all(args: argparse.Namespace) -> int:
     return start_rc or 0
 
 
+def _resolve_reflexio_url() -> str:
+    """Return the URL endpoint for the local claude-smart reflexio backend.
+
+    Mirrors ``claude_smart.reflexio_adapter`` so the CLI's one-shot
+    ReflexioClient calls hit the same server as the long-lived adapter
+    used by hook handlers.
+
+    Returns:
+        str: The ``REFLEXIO_URL`` env var if set, otherwise the default
+            local backend endpoint.
+    """
+    return os.environ.get("REFLEXIO_URL", "http://localhost:8071/")
+
+
+def _format_deleted_counts(deleted_counts: object) -> str:
+    """Render ``deleted_counts`` from a ``clear_user_data`` response as a summary.
+
+    The backend returns one count per affected table. We surface the
+    total in the headline string (``"removed N row(s)"``) and append a
+    per-table breakdown when at least one bucket is populated, so the
+    operator can tell *what* got cleared at a glance.
+
+    Args:
+        deleted_counts (object): The ``deleted_counts`` field from the
+            backend response. Expected to be a mapping of
+            ``str -> int``; anything else is rendered as ``"unknown"``.
+
+    Returns:
+        str: A short human-readable summary suitable for echoing to
+            stdout (e.g. ``"3 row(s) (interactions=3)"``).
+    """
+    if not isinstance(deleted_counts, dict):
+        return "unknown row(s)"
+    pairs: list[tuple[str, int]] = []
+    for key, value in deleted_counts.items():
+        if isinstance(key, str) and isinstance(value, int):
+            pairs.append((key, value))
+    total = sum(value for _, value in pairs)
+    if not pairs:
+        return f"{total} row(s)"
+    breakdown = ", ".join(f"{name}={count}" for name, count in sorted(pairs))
+    return f"{total} row(s) ({breakdown})"
+
+
+def cmd_clear_user(args: argparse.Namespace) -> int:
+    """Delete one user_id's playbooks, profiles, and interactions via the backend.
+
+    Per-user-scoped counterpart of ``clear-all``. Where ``clear-all`` does
+    a filesystem-level wipe of the entire local storage root, ``clear-user``
+    routes through the running reflexio backend's ``clear_user_data``
+    endpoint so it can scope the deletion to a single ``user_id`` —
+    leaving other users' data and globally-shared ``agent_playbooks``
+    untouched. This is the primitive SWE-bench-style benchmark harnesses
+    need when running many parallel evaluations under distinct synthetic
+    user ids against one shared backend.
+
+    Args:
+        args (argparse.Namespace): Parsed CLI args. Requires
+            ``args.user_id`` (positional) and ``args.yes`` (the
+            destructive-action confirmation flag, matching ``clear-all``).
+
+    Returns:
+        int: 0 on success, 1 if confirmation is missing or the backend
+            call fails.
+    """
+    user_id = args.user_id
+    if not args.yes:
+        sys.stdout.write(
+            f"This will permanently delete all reflexio rows for user '{user_id}' "
+            "(playbooks, profiles, interactions). Other users' data and "
+            "agent_playbooks are not affected.\n"
+            "Re-run with --yes to confirm.\n"
+        )
+        return 1
+
+    try:
+        from reflexio import ReflexioClient  # type: ignore[import-not-found]
+    except ImportError as exc:
+        sys.stderr.write(f"error: reflexio is not installed: {exc}\n")
+        return 1
+
+    try:
+        client = ReflexioClient(url_endpoint=_resolve_reflexio_url())
+        # The companion reflexio PR adds ``clear_user_data``; keep the
+        # CLI buildable until both sides ship together.
+        response = client.clear_user_data(user_id)  # pyright: ignore[reportAttributeAccessIssue]
+    except Exception as exc:  # noqa: BLE001 — surface backend failure verbatim.
+        sys.stderr.write(f"error: clear-user failed: {exc}\n")
+        return 1
+
+    deleted_counts = (
+        response.get("deleted_counts") if isinstance(response, dict) else None
+    )
+    summary = _format_deleted_counts(deleted_counts)
+    sys.stdout.write(f"Cleared user '{user_id}': removed {summary}.\n")
+    return 0
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="claude-smart")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -1625,6 +1724,25 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     ca.set_defaults(func=cmd_clear_all)
 
+    cu = sub.add_parser(
+        "clear-user",
+        help=(
+            "Delete one user_id's playbooks, profiles, and interactions via "
+            "the backend (leaves other users and agent_playbooks intact)"
+        ),
+    )
+    cu.add_argument(
+        "user_id",
+        help="User id whose reflexio rows should be cleared",
+    )
+    cu.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Confirm the destructive clear without prompting",
+    )
+    cu.set_defaults(func=cmd_clear_user)
+
     rs = sub.add_parser(
         "restart",
         help="Restart the reflexio backend and dashboard to pick up changes",

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

@@ -308,10 +308,23 @@ def _resolve_cited_items(session_id: str, cited_ids: list[str]) -> list[dict[str
     return resolved
 
 
-def handle(payload: dict[str, Any]) -> 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
@@ -332,7 +345,7 @@ def handle(payload: dict[str, Any]) -> None:
     )
     if runtime.is_codex():
         if internal_call.is_codex_internal_prompt(prompt):
-            return
+            return None
 
     last_assistant_message = payload.get("last_assistant_message")
     assistant_text = (
@@ -374,7 +387,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
 
 

package/plugin/src/claude_smart/hook_log.py

@@ -0,0 +1,301 @@
+"""Structured, append-only log of every hook fire and its outcome.
+
+Why a dedicated log rather than relying on the Python ``logging`` module:
+hooks run as short-lived subprocesses with no preconfigured handler, so
+``_LOGGER.warning(...)`` calls silently vanish to stderr that Claude Code
+captures but typically does not surface. The dispatcher already wraps
+handlers in a broad ``except`` (so a hook crash never breaks the user's
+session) — without a forensic trail the silent-fail mode is invisible.
+
+This module writes one JSON line per hook fire to
+``~/.claude-smart/hook.log`` from ``hook.main`` after the handler returns.
+The Stop and SessionEnd handlers additionally piggyback their publish
+outcome into the record so the chain hook→adapter→backend is fully
+observable from a single file.
+
+Failure policy: every public function in this module swallows all
+``OSError``/``Exception`` paths. Logging is best-effort; a stuck disk
+or read-only ``$HOME`` must never abort an in-progress hook.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import IO, Any
+
+# ``fcntl`` is POSIX-only. On Windows we skip the cross-process lock and
+# accept the unlikely rotation race (claude-smart is primarily a POSIX
+# tool for Claude Code's plugin runtime).
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover — exercised on Windows only
+    _fcntl = None  # type: ignore[assignment]
+
+_LOGGER = logging.getLogger(__name__)
+
+# Anchored on $HOME so unit tests can monkeypatch ``_LOG_PATH`` to a
+# tmp_path. The directory is created lazily on first write — keeping
+# import side-effect-free matches the rest of the package.
+_LOG_PATH = Path.home() / ".claude-smart" / "hook.log"
+
+_TRUNCATE_LIMIT = 4096
+
+# Hard cap on ``hook.log`` size. At ~400 bytes/line and ~50 lines per
+# typical session, 5 MB ≈ 12k records ≈ a few hundred sessions of recent
+# forensic history — enough to debug the last week, bounded so a power
+# user's log can't grow unbounded.
+_MAX_LOG_BYTES = 5 * 1024 * 1024
+
+
+def log_event(
+    *,
+    event: str,
+    host: str,
+    session_id: Any = None,
+    project_id: Any = None,
+    cwd: Any = None,
+    internal_skipped: bool = False,
+    handler_status: str = "ok",
+    publish_status: str | None = None,
+    publish_count: int | None = None,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Append one JSON record describing a hook fire.
+
+    Args:
+        event (str): Hook event name (``"stop"``, ``"user-prompt"``, …).
+        host (str): Host identifier (``"claude-code"`` / ``"codex"``).
+        session_id (Any): Claude Code session id from the payload, or
+            ``None`` when the payload didn't carry one.
+        project_id (Any): Project-id resolved from ``cwd``. Optional.
+        cwd (Any): Working directory reported by the hook payload.
+            Optional — preserved verbatim so a future audit can correlate
+            fires against workspace directories.
+        internal_skipped (bool): True when ``is_internal_invocation``
+            short-circuited the dispatcher (reflexio-internal sub-claude
+            calls, or invocations from inside the reflexio submodule).
+        handler_status (str): ``"ok"`` for a clean return, ``"unknown_event"``
+            when no handler is registered, or ``"raised:<ExcClass>: <msg>"``
+            when the handler raised — formatted by ``hook.main``.
+        publish_status (str | None): Status returned by
+            ``publish.publish_unpublished`` (``"ok"`` / ``"failed"`` /
+            ``"nothing"``). Only emitted by Stop + SessionEnd.
+        publish_count (int | None): Interaction count from the same
+            tuple. ``None`` when the handler doesn't publish.
+        extra (dict[str, Any] | None): Free-form fields preserved as-is.
+
+    Returns:
+        None
+    """
+    record: dict[str, Any] = {
+        "ts": int(time.time()),
+        "event": event,
+        "host": host,
+        "session_id": _truncate(session_id),
+        "project_id": _truncate(project_id),
+        "cwd": _truncate(cwd),
+        "internal_skipped": bool(internal_skipped),
+        "handler_status": _truncate(handler_status),
+    }
+    if publish_status is not None:
+        record["publish_status"] = publish_status
+        try:
+            record["publish_count"] = int(
+                publish_count if publish_count is not None else 0
+            )
+        except (TypeError, ValueError):
+            # Defensive: a hostile caller passing an unparseable publish_count
+            # must not abort the hook fire. Treat as zero, the record still
+            # writes with publish_status preserved.
+            record["publish_count"] = 0
+    if extra:
+        for key, value in extra.items():
+            if key in record:
+                continue
+            record[key] = _truncate(value)
+
+    try:
+        line = json.dumps(record, ensure_ascii=False, default=str) + "\n"
+    except (TypeError, ValueError) as exc:
+        _LOGGER.debug("hook_log: json encode failed: %s", exc)
+        return
+
+    path = log_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: mkdir for %s failed: %s", path.parent, exc)
+        return
+
+    # Hold an exclusive cross-process flock through the entire append +
+    # rotate critical section. The original rationale ("POSIX atomic
+    # append below PIPE_BUF") protects the *append* alone but not the
+    # ``read_bytes → write tmp → rename`` rotation sequence: a concurrent
+    # appender that lands between rotation's read and rename has its
+    # record silently dropped by the rename. The lock closes that gap.
+    #
+    # On Windows ``_fcntl`` is None and writes proceed unlocked — same
+    # behaviour as before. The original PIPE_BUF-based append atomicity
+    # is preserved by ``_TRUNCATE_LIMIT`` keeping each record below 4 KiB.
+    with _rotation_lock(path):
+        try:
+            with path.open("a", encoding="utf-8") as fh:
+                fh.write(line)
+        except OSError as exc:
+            _LOGGER.debug("hook_log: write to %s failed: %s", path, exc)
+            return
+
+        # Rotate AFTER the append so the just-written record always survives,
+        # even on the call that crosses the cap. A single oversized record
+        # still gets through and is dropped by the *next* rotation when the
+        # file is read back.
+        _maybe_rotate(path)
+
+
+def log_path() -> Path:
+    """Return the active log path, honouring ``CLAUDE_SMART_HOOK_LOG``.
+
+    Resolution order:
+
+    1. ``CLAUDE_SMART_HOOK_LOG`` env var — escape hatch for tests and
+       advanced users who want the log elsewhere.
+    2. ``_LOG_PATH`` module attribute — what monkeypatched tests override.
+    3. ``~/.claude-smart/hook.log`` — the default.
+
+    Returns:
+        Path: The absolute path to write to.
+    """
+    override = os.environ.get("CLAUDE_SMART_HOOK_LOG")
+    if override:
+        return Path(override)
+    return _LOG_PATH
+
+
+def _truncate(value: Any) -> Any:
+    """Cap string values to ``_TRUNCATE_LIMIT`` chars so single-line writes
+    stay below the POSIX atomic-append limit.
+
+    Non-string values pass through unchanged; the json encoder handles
+    them. ``None`` becomes ``null`` in the JSON, which is what we want.
+    """
+    if isinstance(value, str) and len(value) > _TRUNCATE_LIMIT:
+        return value[:_TRUNCATE_LIMIT] + "…"
+    return value
+
+
+@contextlib.contextmanager
+def _rotation_lock(path: Path) -> Iterator[None]:
+    """Hold an exclusive cross-process flock on a sibling ``.lock`` file.
+
+    Serialises every ``log_event`` call against itself so the rotation
+    ``read_bytes → write tmp → rename`` sequence cannot interleave with a
+    concurrent append. On Windows or when the lock cannot be acquired
+    (no ``fcntl``, read-only parent, etc.) the lock degrades to a no-op
+    and the caller proceeds unlocked — matches the pre-existing
+    best-effort policy of this module.
+
+    Args:
+        path (Path): The log file path; the lock file is a sibling at
+            ``<path>.lock``.
+
+    Yields:
+        None.
+    """
+    if _fcntl is None:
+        yield
+        return
+    lock_path = path.with_name(path.name + ".lock")
+    fh: IO[bytes] | None = None
+    try:
+        fh = lock_path.open("ab")
+    except OSError as exc:
+        _LOGGER.debug("hook_log: lock open %s failed: %s", lock_path, exc)
+        yield
+        return
+    try:
+        _fcntl.flock(fh.fileno(), _fcntl.LOCK_EX)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: flock acquire failed: %s", exc)
+        fh.close()
+        yield
+        return
+    try:
+        yield
+    finally:
+        with contextlib.suppress(OSError):
+            _fcntl.flock(fh.fileno(), _fcntl.LOCK_UN)
+        with contextlib.suppress(OSError):
+            fh.close()
+
+
+def _maybe_rotate(path: Path) -> None:
+    """Cap ``path`` at ``_MAX_LOG_BYTES`` by dropping the oldest half in place.
+
+    The fast path is a single ``stat`` syscall — when the file is under
+    the cap (the overwhelmingly common case on every fire) we do nothing.
+    When over the cap we read the file, find the first newline at-or-after
+    the midpoint byte, and atomically replace the original with the bytes
+    *after* that newline. Splitting on a newline boundary preserves the
+    JSON Lines invariant: every retained line is a complete record.
+
+    We picked this over ``logging.handlers.RotatingFileHandler`` because:
+
+    1. ``hook_log`` deliberately avoids the ``logging`` framework — see
+       module docstring. Adding a handler reintroduces the configuration
+       fragility we were dodging.
+    2. ``RotatingFileHandler`` produces ``hook.log.1``, ``hook.log.2`` …
+       sidecar files; our forensic story is "one file, tail it". Users
+       have already wired up tooling around that path.
+    3. In-place truncate-to-second-half is O(n) on the rare rotation
+       event and zero-cost on every other write. Backup file management
+       would add steady-state inode pressure for no benefit.
+
+    Args:
+        path (Path): The log file to inspect. Need not exist — the
+            ``FileNotFoundError`` branch of the ``stat`` call returns
+            cleanly via the ``OSError`` guard.
+
+    Returns:
+        None
+    """
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        _LOGGER.debug("hook_log: stat for rotation failed: %s", exc)
+        return
+
+    if size < _MAX_LOG_BYTES:
+        return
+
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        _LOGGER.debug("hook_log: read for rotation failed: %s", exc)
+        return
+
+    midpoint = len(data) // 2
+    cut = data.find(b"\n", midpoint)
+    # ``find`` returns -1 when the second half has no newline at all,
+    # meaning the file is one giant record with no framing left to
+    # preserve. Drop the lot rather than split a record mid-byte.
+    tail = b"" if cut == -1 else data[cut + 1 :]
+
+    # Atomic replace: write to a sibling temp file then rename. This
+    # avoids the truncation window where a concurrent reader would see
+    # an empty file, and matches the contract that ``hook.log`` always
+    # contains complete JSONL framing.
+    tmp_path = path.with_name(path.name + ".rot")
+    try:
+        tmp_path.write_bytes(tail)
+        tmp_path.replace(path)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: rotation rename failed: %s", exc)
+        # Best-effort cleanup of the temp file; ignore failures.
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)

package/plugin/uv.lock

@@ -419,7 +419,7 @@ wheels = [
 
 [[package]]
 name = "claude-smart"
-version = "0.2.30"
+version = "0.2.31"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },