claude-code-arcane 2.14.0 → 2.15.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [2.15.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.14.0...v2.15.0) (2026-10-16)
+
+
+### Features
+
+* **hooks:** watch the session for loops, scope and unchecked edits ([84d7c3e](https://github.com/SebastianLuser/claude-code-arcane/commit/84d7c3eccc33380f27d7f8901affedb090ee21d5))
+* **installer:** wire the session watch and feed it the real context window ([615d212](https://github.com/SebastianLuser/claude-code-arcane/commit/615d212d96744c180fe9f84f7670382ec58d2772))
+
 # [2.14.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.13.0...v2.14.0) (2026-10-16)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **437 skills, 115 agents, 17 hooks and 36 rules for Claude Code — selective deploy by profile.**
+> **437 skills, 115 agents, 18 hooks and 36 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 

package/dist/cli.js

@@ -880,16 +880,19 @@ var FILE_TOOLS_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
 var LEGACY_COMMAND = /^bash \.claude\/hooks\/([\w.-]+\.sh)$/;
 var ARCANE_COMMAND = /^bash "?(?:\$CLAUDE_PROJECT_DIR\/|[^"]*\/)?\.claude\/hooks\/([\w.-]+\.sh)"?$/;
 var RETIRED_SCRIPTS = /* @__PURE__ */ new Set(["validate-push.sh", "validate-secrets.sh"]);
-function hookCommand(target, script) {
+function hookCommand(target, script, args = "") {
+  const suffix = args ? ` ${args}` : "";
   if (path8.resolve(target) === path8.resolve(os2.homedir())) {
     const absolute = path8.join(target, ".claude", "hooks", script).replace(/\\/g, "/");
-    return `bash "${absolute}"`;
+    return `bash "${absolute}"${suffix}`;
   }
-  return `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/${script}"`;
+  return `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/${script}"${suffix}`;
 }
-function hook(target, script, timeout) {
-  return { type: "command", command: hookCommand(target, script), timeout };
+function hook(target, script, timeout, args = "") {
+  return { type: "command", command: hookCommand(target, script, args), timeout };
 }
+var WATCH_POST_TOOL = ["run-py.sh", "session_watch.py post-tool"];
+var WATCH_STOP = ["run-py.sh", "session_watch.py stop"];
 function defaultHooks(target) {
   const one = (script, timeout) => [
     { matcher: "", hooks: [hook(target, script, timeout)] }
@@ -921,13 +924,21 @@ function defaultHooks(target) {
       {
         matcher: "Write|Edit",
         hooks: [hook(target, "validate-assets.sh", 10), hook(target, "validate-skill-change.sh", 5)]
-      }
+      },
+      { matcher: "", hooks: [hook(target, WATCH_POST_TOOL[0], 10, WATCH_POST_TOOL[1])] }
     ],
     Notification: one("notify.sh", 10),
     PreCompact: one("pre-compact.sh", 10),
     PostCompact: one("post-compact.sh", 10),
     Stop: [
-      { matcher: "", hooks: [hook(target, "session-stop.sh", 10), hook(target, "worktree-stop.sh", 10)] }
+      {
+        matcher: "",
+        hooks: [
+          hook(target, "session-stop.sh", 10),
+          hook(target, "worktree-stop.sh", 10),
+          hook(target, WATCH_STOP[0], 120, WATCH_STOP[1])
+        ]
+      }
     ],
     SubagentStart: one("log-agent.sh", 5),
     SubagentStop: one("log-agent-stop.sh", 5)
@@ -975,15 +986,21 @@ function healHooks(hooks, target) {
     pre.push({ matcher: FILE_TOOLS_MATCHER, hooks: [hook(target, "guard.sh", 10)] });
     changes.push("guard for file edits");
   }
-  const stop = hooks.Stop ??= [];
-  if (!stop.some((g) => g.hooks?.some((h) => h.command?.includes("worktree-stop.sh")))) {
-    const group = stop.find((g) => !g.matcher);
-    if (group) group.hooks = [...group.hooks ?? [], hook(target, "worktree-stop.sh", 10)];
-    else stop.push({ matcher: "", hooks: [hook(target, "worktree-stop.sh", 10)] });
-    changes.push("worktree exit on stop");
-  }
+  ensureHook(hooks, "Stop", hook(target, "worktree-stop.sh", 10), "worktree exit on stop", changes);
+  ensureHook(hooks, "Stop", hook(target, WATCH_STOP[0], 120, WATCH_STOP[1]), "format and type check on stop", changes);
+  ensureHook(hooks, "PostToolUse", hook(target, WATCH_POST_TOOL[0], 10, WATCH_POST_TOOL[1]), "session watch", changes);
   return changes;
 }
+function ensureHook(hooks, event, entry, label, changes) {
+  const signature = entry.command.replace(/^bash "[^"]*\/hooks\//, "");
+  const groups = hooks[event] ??= [];
+  const present = groups.some((g) => g.hooks?.some((h) => h.command?.endsWith(signature)));
+  if (present) return;
+  const group = groups.find((g) => !g.matcher);
+  if (group) group.hooks = [...group.hooks ?? [], entry];
+  else groups.push({ matcher: "", hooks: [entry] });
+  changes.push(label);
+}
 
 // src/installer.ts
 var SETTINGS_TEMPLATE = {

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **17 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **18 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -239,7 +239,7 @@ Every installation automatically loads `core.yaml` first:
 |----------|----------|
 | **Skills (21)** | commit, create-pr, changelog, check, code-review, context-prime, help, start, fix-issue, hotfix, brainstorm, scope-check, reverse-document, skill-improve, skill-test, tech-debt, arcane-status, arcane-list, arcane-add, arcane-remove, arcane-clean |
 | **Rules (8)** | data-files, prototype-code, test-standards, implementation-workflow, code-comments, verification, agent-delegation, git-worktrees |
-| **Hooks (16)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, worktree-stop, log-agent, log-agent-stop |
+| **Hooks (17)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, worktree-stop, run-py (session_watch), log-agent, log-agent-stop |
 | **Agents (1 dir)** | quality |
 | **Permissions** | 15 allow (git, ls, gh pr/issue/run and read-only gh, curl) + 13 deny (force push, reset --hard, clean -f, sudo, .env, etc.) |
 

package/docs/context-management.md

@@ -48,6 +48,7 @@ Esto mantiene el context window con ~3-5k tokens (solo la sección actual) en ve
 ## Proactive Compaction
 
 - **Compactá proactivamente** a ~60-70% de uso, no reactivamente al límite
+- **Aviso automático:** con el profile `statusline`, `session_watch.py` avisa a Claude al 70% y al 85% de la ventana real (la statusline anota el tamaño que reporta Claude Code en `.claude/session-state/context.json`). Sin statusline no avisa: adivinar la ventana haría saltar el aviso demasiado temprano en sesiones de 1M
 - **Usá `/clear`** entre tareas no relacionadas, o después de 2+ intentos de corrección fallidos
 - **Puntos naturales de compaction:** después de escribir una sección al archivo, después de un commit, después de completar una tarea, antes de empezar un tema nuevo
 - **Focused compaction:** `/compact Focus on [tarea actual] — secciones 1-3 ya escritas al archivo, working on sección 4`

package/docs/directory-structure.md

@@ -125,9 +125,10 @@ Los eventos los define `src/installer.ts` al generar `settings.json`, no los pro
 | PreToolUse (`Bash`) | `guard.sh` → `validate-commit.sh` |
 | PreToolUse (`Write\|Edit\|MultiEdit\|NotebookEdit`) | `guard.sh` |
 | PostToolUse (`Write\|Edit`) | `validate-assets.sh`, `validate-skill-change.sh` |
+| PostToolUse (todas) | `run-py.sh session_watch.py post-tool` (ediciones, loops, alcance, aviso de compactación) |
 | Notification | `notify.sh` |
 | PreCompact / PostCompact | `pre-compact.sh` / `post-compact.sh` |
-| Stop | `session-stop.sh`, `worktree-stop.sh` |
+| Stop | `session-stop.sh`, `worktree-stop.sh`, `run-py.sh session_watch.py stop` (format + type check de lo editado) |
 | SubagentStart / SubagentStop | `log-agent.sh` / `log-agent-stop.sh` |
 
 Cada comando es `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/<script>"`: dentro de un worktree los hooks corren parados en el worktree, que puede no tener `.claude/hooks/` commiteado, y la variable siempre apunta al proyecto donde arrancó la sesión. `arcane update` migra las instalaciones que tenían la ruta relativa.

package/hooks/run-py.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Runs a Python hook from this folder: run-py.sh <script.py> [args...]
+#
+# Uses the first Python that actually starts (on Windows `python3` can be the
+# Microsoft Store stub, which exits non-zero instead of running). With no working
+# Python the hook does nothing.
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$1"
+shift
+[ -f "$DIR/$SCRIPT" ] || exit 0
+INPUT=$(cat)
+
+for PY in python3 python py; do
+  command -v "$PY" >/dev/null 2>&1 || continue
+  if OUT=$(printf '%s' "$INPUT" | "$PY" "$DIR/$SCRIPT" "$@" 2>/dev/null); then
+    printf '%s' "$OUT"
+    exit 0
+  fi
+done
+exit 0

package/hooks/session_watch.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""Session watch: cheap, deterministic signals the model should not have to remember.
+
+`session_watch.py post-tool` (PostToolUse, every tool):
+  - records each file Claude edits, for the Stop check below;
+  - warns when the same tool runs with the same input 5 times in a row (a loop);
+  - warns once when a session has edited 15 files (scope drift);
+  - warns when the context passes 70% and 85% of the real window, so active.md is
+    brought up to date before a compaction. The window size comes from the status
+    line (statusline.sh caches what Claude Code reports); without it, no warning,
+    since guessing the window would warn far too early on 1M-token sessions.
+
+`session_watch.py stop` (Stop): formats the files edited this turn and type-checks
+them with the project's own tools (Prettier or Biome + tsc, gofmt + go vet,
+dotnet format). Only errors in files edited this turn block the stop, once, so
+errors the project already had never trap a session.
+
+State lives in .claude/session-state/watch-<session>.json, which ignores itself.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+LOOP_LENGTH = 5
+SCOPE_FILES = 15
+CONTEXT_WARNINGS = (70, 85)
+FILE_TOOLS = {"Write", "Edit", "MultiEdit", "NotebookEdit"}
+IGNORED_INPUT_KEYS = {"description", "timeout"}
+CHECK_TIMEOUT = 90
+MAX_REPORT_LINES = 25
+
+
+# --- state -------------------------------------------------------------------
+
+def state_dir(project: str) -> str:
+    path = os.path.join(project, ".claude", "session-state")
+    os.makedirs(path, exist_ok=True)
+    ignore = os.path.join(path, ".gitignore")
+    if not os.path.exists(ignore):
+        with open(ignore, "w", encoding="utf-8") as f:
+            f.write("*\n")
+    return path
+
+
+def load_state(project: str, session: str) -> dict:
+    path = os.path.join(state_dir(project), f"watch-{safe(session)}.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {}
+
+
+def save_state(project: str, session: str, state: dict) -> None:
+    path = os.path.join(state_dir(project), f"watch-{safe(session)}.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f)
+
+
+def safe(session: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_-]", "", session or "default")[:64] or "default"
+
+
+# --- post-tool -----------------------------------------------------------------
+
+def post_tool(payload: dict, project: str) -> list[str]:
+    """Update the session state and return the warnings to show Claude."""
+    session = payload.get("session_id", "")
+    state = load_state(project, session)
+    warnings: list[str] = []
+    tool = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input") or {}
+
+    if tool in FILE_TOOLS:
+        path = tool_input.get("file_path") or tool_input.get("notebook_path")
+        if path:
+            absolute = os.path.abspath(os.path.join(project, path))
+            pending = state.setdefault("pending", [])
+            if absolute not in pending:
+                pending.append(absolute)
+            edited = state.setdefault("edited", [])
+            if absolute not in edited:
+                edited.append(absolute)
+            if len(edited) >= SCOPE_FILES and not state.get("scope_warned"):
+                state["scope_warned"] = True
+                warnings.append(f"This session has edited {len(edited)} files. Check the change is still "
+                                "within the task's scope before going further.")
+
+    # The description is Claude's label for the call ("call 2 of 6"), not what runs.
+    action = {k: v for k, v in tool_input.items() if k not in IGNORED_INPUT_KEYS}
+    digest = hashlib.sha1(json.dumps([tool, action], sort_keys=True).encode()).hexdigest()
+    recent = (state.get("recent", []) + [digest])[-LOOP_LENGTH:]
+    state["recent"] = recent
+    if len(recent) == LOOP_LENGTH and len(set(recent)) == 1 and state.get("loop_warned") != digest:
+        state["loop_warned"] = digest
+        warnings.append(f"{tool} ran {LOOP_LENGTH} times in a row with the same input. Stop repeating it: "
+                        "name the assumption that may be wrong, or ask the user one diagnostic question.")
+
+    used = context_used(project, session)
+    if used is not None:
+        for level in CONTEXT_WARNINGS:
+            if used >= level and state.get("context_warned", 0) < level:
+                state["context_warned"] = level
+                warnings.append(f"Context is at {used:.0f}% of the window. At the next logical point "
+                                "(a commit, a finished step), update .claude/session-state/active.md if this "
+                                "task has one, then suggest the user run /compact.")
+                break
+
+    save_state(project, session, state)
+    return warnings
+
+
+def context_used(project: str, session: str) -> float | None:
+    """Percent of the real context window in use, as the status line last saw it."""
+    path = os.path.join(project, ".claude", "session-state", "context.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    if data.get("session_id") != session:
+        return None
+    try:
+        return float(data["used_percentage"])
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+# --- stop ----------------------------------------------------------------------
+
+def find_up(start: str, names: tuple[str, ...], stop_at: str) -> str | None:
+    """Nearest ancestor of `start` (up to `stop_at`) containing one of `names`."""
+    current = os.path.dirname(start)
+    stop_at = os.path.abspath(stop_at)
+    while True:
+        if any(os.path.exists(os.path.join(current, n)) for n in names):
+            return current
+        if os.path.abspath(current) == stop_at or os.path.dirname(current) == current:
+            return None
+        current = os.path.dirname(current)
+
+
+def local_bin(root: str, name: str) -> str | None:
+    """A tool installed in the project; never one npx would download."""
+    for folder in (root, os.path.dirname(root)):
+        base = os.path.join(folder, "node_modules", ".bin", name)
+        for candidate in ((base + ".cmd", base) if os.name == "nt" else (base,)):
+            if os.path.exists(candidate):
+                return candidate
+    return None
+
+
+def plan_checks(files: list[str], project: str) -> list[dict]:
+    """Group edited files by project root and pick the format and check commands."""
+    plans: dict[tuple, dict] = {}
+
+    def add(key: tuple, cwd: str, fmt: list | None, check: list | None, file: str) -> None:
+        plan = plans.setdefault(key, {"cwd": cwd, "format": fmt, "check": check, "files": []})
+        plan["files"].append(file)
+
+    for file in files:
+        if not os.path.exists(file):
+            continue
+        ext = os.path.splitext(file)[1].lower()
+        if ext in (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".css", ".scss", ".md"):
+            root = find_up(file, ("package.json",), project)
+            if not root:
+                continue
+            fmt = None
+            biome = local_bin(root, "biome")
+            prettier = local_bin(root, "prettier")
+            if biome and any(os.path.exists(os.path.join(root, n)) for n in ("biome.json", "biome.jsonc")):
+                fmt = [biome, "format", "--write"]
+            elif prettier:
+                fmt = [prettier, "--write", "--log-level", "warn"]
+            check = None
+            if ext in (".ts", ".tsx"):
+                tsconfig = find_up(file, ("tsconfig.json",), project)
+                tsc = local_bin(root, "tsc")
+                if tsconfig and tsc:
+                    check = [tsc, "--noEmit", "--pretty", "false", "-p", os.path.join(tsconfig, "tsconfig.json")]
+            add(("node", root, tuple(check or ())), root, fmt, check, file)
+        elif ext == ".go" and shutil.which("gofmt"):
+            root = find_up(file, ("go.mod",), project)
+            if root:
+                rel = "./" + os.path.relpath(os.path.dirname(file), root).replace("\\", "/")
+                check = ["go", "vet", rel] if shutil.which("go") else None
+                add(("go", root, rel), root, ["gofmt", "-w"], check, file)
+        elif ext == ".cs" and shutil.which("dotnet"):
+            root = find_up(file, (".editorconfig",), project) or project
+            add(("dotnet", root), root, ["dotnet", "format", "whitespace", ".", "--folder", "--include"], None, file)
+    return list(plans.values())
+
+
+def run(command: list[str], cwd: str) -> tuple[int, str]:
+    try:
+        result = subprocess.run(command, cwd=cwd, capture_output=True, text=True,
+                                timeout=CHECK_TIMEOUT, encoding="utf-8", errors="replace")
+        return result.returncode, (result.stdout or "") + (result.stderr or "")
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return 0, f"skipped: {error}"
+
+
+def errors_in(output: str, files: list[str], cwd: str) -> list[str]:
+    """Error lines that name one of `files`; errors elsewhere predate this turn."""
+    wanted = {os.path.normcase(os.path.abspath(f)) for f in files}
+    lines = []
+    for line in output.splitlines():
+        match = re.match(r"^(.+?)(?:\(\d+,\d+\)|:\d+:\d+)", line.strip())
+        if not match:
+            continue
+        candidate = os.path.normcase(os.path.abspath(os.path.join(cwd, match.group(1).strip())))
+        if candidate in wanted:
+            lines.append(line.strip())
+    return lines
+
+
+def stop(payload: dict, project: str) -> dict | None:
+    session = payload.get("session_id", "")
+    state = load_state(project, session)
+    files = state.pop("pending", [])
+    save_state(project, session, state)
+    if not files or payload.get("stop_hook_active"):
+        return None
+
+    problems: list[str] = []
+    for plan in plan_checks(files, project):
+        if plan["format"]:
+            run(plan["format"] + plan["files"], plan["cwd"])
+        if plan["check"]:
+            code, output = run(plan["check"], plan["cwd"])
+            if code != 0:
+                problems.extend(errors_in(output, plan["files"], plan["cwd"]))
+    if not problems:
+        return None
+    shown = problems[:MAX_REPORT_LINES]
+    more = f"\n... and {len(problems) - len(shown)} more" if len(problems) > len(shown) else ""
+    return {
+        "decision": "block",
+        "reason": "The type check found errors in files you edited this turn. Fix them before finishing:\n"
+                  + "\n".join(shown) + more,
+    }
+
+
+# --- entry point ---------------------------------------------------------------
+
+def main() -> int:
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except ValueError:
+        return 0
+    project = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
+    if mode == "post-tool":
+        warnings = post_tool(payload, project)
+        if warnings:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "Arcane session watch: " + " ".join(warnings),
+            }}))
+    elif mode == "stop":
+        decision = stop(payload, project)
+        if decision:
+            print(json.dumps(decision))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # a watch bug must never break the session
+        sys.exit(0)

package/hooks/statusline.sh

@@ -75,6 +75,21 @@ if isinstance(cw, dict) and cw:
             pct = float(up)
         except Exception:
             pct = None
+    # Hooks never see the window size; session_watch.py reads it from here to warn
+    # before a compaction at a share of the real window instead of a guessed one.
+    project_dir = (data.get("workspace") or {}).get("project_dir") or data.get("cwd") or ""
+    if pct is not None and project_dir and os.path.isdir(os.path.join(project_dir, ".claude")):
+        try:
+            state = os.path.join(project_dir, ".claude", "session-state")
+            os.makedirs(state, exist_ok=True)
+            ignore = os.path.join(state, ".gitignore")
+            if not os.path.exists(ignore):
+                open(ignore, "w").write("*\n")
+            with open(os.path.join(state, "context.json"), "w") as f:
+                json.dump({"session_id": data.get("session_id"), "used_percentage": pct,
+                           "context_window_size": limit}, f)
+        except Exception:
+            pass
 
 # Fallback (older Claude Code without context_window): scan transcript usage.
 if total is None:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/core.yaml

@@ -58,6 +58,7 @@ hooks:
   - post-compact.sh
   - session-stop.sh
   - worktree-stop.sh
+  - run-py.sh
   - log-agent.sh
   - log-agent-stop.sh