pi-dev-team 0.2.0

package/hooks/code_intelligence_nudge.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""code_intelligence_nudge — Claude Code PreToolUse hook.
+
+Renamed/generalized from codegraph_nudge.py (#593 / #572 Phase 3, #1368)
+now that this hook nudges agents toward whichever of CodeGraph, Repowise,
+and Graphify are indexed in the project, not CodeGraph alone.
+`_detect_present_tools()` reports which of the three are present;
+`_compose_message()` composes a single-tool or precedence-ordered
+combined message for whichever of those are not already used this turn.
+
+Runs before Read, Grep, Glob tool calls. Single-file Read calls, Grep with
+a file `path`, and Glob with a literal `pattern` pass silently.
+
+Contract (docs/python-hook-contract.md):
+    Input : PreToolUse JSON on stdin
+    Output: warning on stderr when exploration is detected
+    Exit  : 0 = allow (silent or warn). 2 = block (careful mode only).
+
+Posture: fail-open. Any internal error → exit 0. The hook is a nudge,
+never a gate.
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+
+sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths  # type: ignore[import-not-found]
+
+try:
+    from stdin_json import read_stdin_json  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover
+
+    def read_stdin_json() -> dict | None:  # type: ignore[misc]
+        return None
+
+try:
+    from turn_identity import (  # type: ignore[import-not-found]
+        SENTINEL_RELATIVE_PATH,
+        count_user_lines,
+        matches_current_turn,
+        transcript_id,
+    )
+except ImportError:  # pragma: no cover
+
+    SENTINEL_RELATIVE_PATH = Path(".claude") / "code-intelligence-turn-state.json"  # type: ignore[misc]
+
+    def transcript_id(path: str) -> str:  # type: ignore[misc]
+        return Path(path).stem
+
+    def count_user_lines(transcript_path: Path) -> int:  # type: ignore[misc]
+        return 0
+
+    def matches_current_turn(sentinel: dict, tid: str, tc: int) -> bool:  # type: ignore[misc]
+        sentinel_tid = str(sentinel.get("transcript_id") or "")
+        if sentinel_tid != tid:
+            return False
+        try:
+            return int(sentinel.get("turn_counter")) == tc
+        except (TypeError, ValueError):
+            return False
+
+
+_CUES = {
+    "graphify": (
+        'graphify query "<question>" — cross-artifact: code + docs + schemas + '
+        "infra (non-code content; not a faster CodeGraph/Repowise)"
+    ),
+    "repowise": (
+        "repowise get_context / get_risk / get_why — risk, rationale, code "
+        "health, dead code (not raw call-graph structure)"
+    ),
+    "codegraph": (
+        "codegraph_explore — structure, call graph, blast radius (not risk, "
+        "rationale, or non-code content)"
+    ),
+}
+
+_LABELS = {"graphify": "Graphify", "repowise": "Repowise", "codegraph": "CodeGraph"}
+
+# Fixed message order — never the filesystem/detection order the caller passes in.
+# This specific order (graphify, repowise, codegraph) was chosen during plan
+# review to remove the CodeGraph-first primacy bias that motivated this whole
+# generalization (#1368): CodeGraph used to be the only tool this hook named,
+# so listing it first here would silently re-establish it as the "default,
+# most-likely-tried" tool. Graphify and Repowise get equal billing ahead of
+# it instead.
+_PRECEDENCE = ["graphify", "repowise", "codegraph"]
+
+_CLOSING_LINE = "Grep/Glob/Read for confirming a specific detail."
+
+
+def _cue_line(tool: str, *, bulleted: bool) -> str:
+    """Format one tool's cue — bulleted for the combined message, bare for
+    the single-tool message. Shared by both `_compose_message` branches so
+    the underlying cue text can't drift between the two message shapes."""
+    return f"- {_CUES[tool]}" if bulleted else _CUES[tool]
+
+
+def _compose_message(qualifying: list) -> str | None:
+    """Compose the nudge message for the given qualifying tools.
+
+    `qualifying` is reordered by `_PRECEDENCE` before composing — the
+    message's tool order never varies with filesystem/detection order.
+    Zero qualifying tools → None (full suppression).
+    """
+    ordered = [tool for tool in _PRECEDENCE if tool in qualifying]
+    if not ordered:
+        return None
+
+    if len(ordered) == 1:
+        tool = ordered[0]
+        return (
+            f"[code-intelligence-nudge] {_LABELS[tool]} is initialized in this "
+            f"project. Prefer {_cue_line(tool, bulleted=False)} for multi-file "
+            f"exploration; {_CLOSING_LINE}"
+        )
+
+    bullets = "\n".join(_cue_line(tool, bulleted=True) for tool in ordered)
+    return (
+        "[code-intelligence-nudge] Multiple code-intelligence indexes found. "
+        f"Pick whichever matches your question:\n{bullets}\n{_CLOSING_LINE}"
+    )
+
+
+def _tools_used_this_turn(cwd: Path, transcript_path: str) -> list:
+    """Which tool families ran earlier in the current turn, per the
+    accumulating sentinel `code_intelligence_turn_mark.py` writes at
+    `$cwd/.claude/code-intelligence-turn-state.json`.
+
+    Cross-checks the sentinel's `transcript_id`/`turn_counter` against the
+    freshly computed values (same turn-identity computation the write side
+    uses, via turn_identity.py) — a mismatch means a new turn/transcript, so
+    the sentinel doesn't apply. A missing file, an unparseable/non-dict
+    payload, a mismatched identity, or a `tools_used` field that's missing
+    or not a list (legacy pre-Slice-2 schema, or corrupt) all resolve to
+    `[]` — fail-open, never a crash.
+    """
+    sentinel = cwd / SENTINEL_RELATIVE_PATH
+    if not sentinel.is_file():
+        return []
+    if not transcript_path:
+        return []
+    tx = Path(transcript_path)
+    if not tx.is_file():
+        return []
+    try:
+        sentinel_data = json.loads(sentinel.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    if not isinstance(sentinel_data, dict):
+        return []
+
+    current_tid = transcript_id(transcript_path)
+    current_tc = count_user_lines(tx)
+    if not matches_current_turn(sentinel_data, current_tid, current_tc):
+        return []
+
+    tools_used = sentinel_data.get("tools_used")
+    if not isinstance(tools_used, list):
+        return []
+    return tools_used
+
+
+def _is_multi_grep(tool_input: dict) -> bool:
+    """Grep is multi-file unless `path` is set AND points at a regular file."""
+    path = str(tool_input.get("path") or "")
+    if not path:
+        return True
+    return not Path(path).is_file()
+
+
+def _is_multi_glob(tool_input: dict) -> bool:
+    """Glob is multi when the pattern contains a glob metacharacter."""
+    pattern = str(tool_input.get("pattern") or "")
+    return any(c in pattern for c in ("*", "?", "["))
+
+
+def _detect_present_tools(cwd: Path) -> list:
+    """Return which of codegraph/repowise/graphify are indexed in `cwd`.
+
+    codegraph: `.codegraph/` directory. repowise: `.repowise/` directory.
+    graphify: `graphify-out/graph.json` regular file. Each check is wrapped
+    so any OSError (wrong type — e.g. a file where a dir is expected, or a
+    permission error) is treated as "not present," never raised — this
+    hook is a nudge, never a gate.
+    """
+    present = []
+    try:
+        if (cwd / ".codegraph").is_dir():
+            present.append("codegraph")
+    except OSError:
+        pass
+    try:
+        if (cwd / ".repowise").is_dir():
+            present.append("repowise")
+    except OSError:
+        pass
+    try:
+        if (cwd / "graphify-out" / "graph.json").is_file():
+            present.append("graphify")
+    except OSError:
+        pass
+    return present
+
+
+def _careful_active(careful_path: Path) -> bool:
+    """Read careful-state.json's `active` field; True iff it is `True`.
+
+    `careful_path` is resolved by the caller via
+    `artifact_paths.resolve_file()`, keyed off the payload's own `cwd`
+    (#1900 follow-up in this file — the identical bug class already fixed
+    in `destructive_guard.py`: `/careful`/`/guard` only ever write the
+    per-repo `<repo-root>/.claude/hooks/careful-state.json`, never a path
+    relative to this hook's own script directory, which in a real
+    installed session is the shared plugin-cache directory — one location
+    shared by every concurrently-running session, worktree, and project on
+    the machine).
+    """
+    if not careful_path.is_file():
+        return False
+    try:
+        data = json.loads(careful_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return data.get("active") is True
+
+
+def main() -> int:
+    payload = read_stdin_json()
+    if payload is None:
+        return 0
+
+    cwd_str = str(payload.get("cwd") or "").strip()
+    cwd = Path(cwd_str) if cwd_str else Path.cwd()
+
+    tool_name = str(payload.get("tool_name") or "")
+
+    # Read always targets exactly one file_path — never exploration.
+    if tool_name == "Read":
+        return 0
+
+    tool_input = payload.get("tool_input") or {}
+    if not isinstance(tool_input, dict):
+        return 0
+
+    if tool_name == "Grep":
+        is_multi = _is_multi_grep(tool_input)
+    elif tool_name == "Glob":
+        is_multi = _is_multi_glob(tool_input)
+    else:
+        # Other tools — defensive default, pass silently.
+        return 0
+
+    if not is_multi:
+        return 0
+
+    qualifying = _detect_present_tools(cwd)
+    if not qualifying:
+        return 0
+
+    transcript_path = str(payload.get("transcript_path") or "")
+    used_this_turn = set(_tools_used_this_turn(cwd, transcript_path))
+    qualifying = [tool for tool in qualifying if tool not in used_this_turn]
+
+    message = _compose_message(qualifying)
+    if message is None:
+        return 0
+
+    careful_path = artifact_paths.resolve_file(
+        "hooks", "careful-state.json", root=cwd, migrate=False
+    )
+    if _careful_active(careful_path):
+        print(f"{message} [blocked by /careful]", file=sys.stderr)
+        return 2
+
+    print(message, file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # noqa: BLE001 -- fail-open on any unexpected error; the hook is a nudge, never a gate
+        sys.exit(0)

package/hooks/code_intelligence_turn_mark.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Renamed/generalized from codegraph_turn_mark.py (#594 / #572 Phase 3, #1368).
+
+Claude Code PostToolUse hook. Fires after a tool call completes and
+`_tool_family()` recognizes its name as belonging to a supported
+code-intelligence tool family — currently `mcp__codegraph__*` ("codegraph")
+and `mcp__plugin_repowise_repowise__*` ("repowise"). Writes a sentinel at
+`${CLAUDE_PROJECT_DIR:-$PWD}/.claude/code-intelligence-turn-state.json` that
+the nudge hook (`code_intelligence_nudge.py`) will consult (Step 2.3) to
+suppress its warning for whichever tool family was used during the rest of
+the current turn.
+
+`transcript_id`/`count_user_lines` are imported from the shared
+`hooks/lib/turn_identity.py` module (falling back to local reimplementations
+only if that import fails) so this hook and the nudge hook can never drift
+apart on how a "turn" is identified. The same module's `matches_current_turn`
+owns the identity-match predicate for both this hook's read-modify-write
+merge and the nudge hook's read-side suppression check.
+
+Sentinel schema (Step 2.2 — accumulating `tools_used` list, written to
+`.claude/code-intelligence-turn-state.json`):
+    { "transcript_id": <string>, "turn_counter": <int>, "tools_used": [<string>, ...] }
+    - transcript_id: basename of transcript_path with extension stripped
+    - turn_counter:  count of `"type":"user"` lines in the transcript file,
+                     scanning only the last 1 MiB so a monotonically growing
+                     transcript stays O(1) per fire (same cap the nudge hook
+                     applies on its side).
+    - tools_used:    families (e.g. "codegraph", "repowise") recognized so
+                     far this turn, in first-used order, deduplicated.
+
+Before writing, any existing sentinel is read back. When its transcript_id
+and turn_counter match the freshly computed values (same turn), the newly
+recognized family is merged into the existing `tools_used` list (deduped,
+order preserved); otherwise — new turn, new transcript, or a
+missing/legacy/corrupt sentinel — the sentinel is rewritten from scratch
+with only the new family. A `tools_used` field that exists but isn't a
+list, or a sentinel that fails to parse at all, is treated as an empty list
+rather than raised (fail-open on the write side, mirroring the nudge hook's
+read-side handling of the same shapes).
+
+Both `transcript_id`/`turn_counter` are computed the same way the nudge hook
+recomputes them at PreToolUse time, so a same-turn match accumulates and a
+next-turn mismatch (new user message → counter bumps) resets it.
+
+Contract (docs/python-hook-contract.md):
+    Input : PostToolUse JSON on stdin
+    Output: writes sentinel file; no stdout. Exit 0.
+    Posture: fail-open. Any internal error → exit 0; sentinel may not be
+             written, the nudge hook will simply emit its (advisory) warning.
+
+Stdlib-only (json/os/pathlib/sys/tempfile). See ADR 0014.
+
+Refs: #572 (bash → Python migration epic), #1368 (multi-tool nudge).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+try:
+    import fcntl  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover — Windows has no fcntl
+    fcntl = None  # type: ignore[assignment]
+
+try:
+    import msvcrt  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover — POSIX has no msvcrt
+    msvcrt = None  # type: ignore[assignment]
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+
+sys.path.insert(0, str(_LIB_DIR))
+try:
+    from turn_identity import (  # type: ignore[import-not-found]
+        SENTINEL_RELATIVE_PATH,
+        count_user_lines,
+        matches_current_turn,
+        transcript_id,
+    )
+except ImportError:  # pragma: no cover
+
+    SENTINEL_RELATIVE_PATH = Path(".claude") / "code-intelligence-turn-state.json"  # type: ignore[misc]
+
+    def transcript_id(path: str) -> str:  # type: ignore[misc]
+        return Path(path).stem
+
+    def count_user_lines(transcript_path: Path) -> int:  # type: ignore[misc]
+        return 0
+
+    def matches_current_turn(sentinel: dict, tid: str, tc: int) -> bool:  # type: ignore[misc]
+        sentinel_tid = str(sentinel.get("transcript_id") or "")
+        if sentinel_tid != tid:
+            return False
+        try:
+            return int(sentinel.get("turn_counter")) == tc
+        except (TypeError, ValueError):
+            return False
+
+
+from stdin_json import read_stdin_json  # type: ignore[import-not-found]
+
+
+def _tool_family(name: str) -> str | None:
+    """Classify a tool name into the family whose usage this hook marks.
+
+    Same prefix filter the .sh applied via
+    `case "$TOOL_NAME" in mcp__codegraph__*)`, generalized to also recognize
+    Repowise's MCP server prefix. Any other tool name (or a name matching
+    neither prefix) returns None.
+    """
+    if name.startswith("mcp__codegraph__"):
+        return "codegraph"
+    if name.startswith("mcp__plugin_repowise_repowise__"):
+        return "repowise"
+    return None
+
+
+def _existing_tools_used(sentinel: Path, tid: str, tc: int) -> list:
+    """Read back any prior sentinel's `tools_used` for the current turn.
+
+    Fail-open on every corrupt/legacy shape — an unreadable file, invalid
+    JSON, a non-dict payload, a mismatched transcript/turn (new turn), a
+    missing `tools_used` field (legacy pre-Slice-2 schema), or a
+    `tools_used` present but not a list — all resolve to "start fresh",
+    i.e. an empty list, never a raised exception. The same-turn check
+    itself is `turn_identity.matches_current_turn` — the single predicate
+    shared with the nudge hook's read side, so the two sides of the
+    sentinel contract can't drift on turn-counter coercion.
+    """
+    if not sentinel.is_file():
+        return []
+    try:
+        existing = json.loads(sentinel.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return []
+    if not isinstance(existing, dict):
+        return []
+    if not matches_current_turn(existing, tid, tc):
+        return []
+    tools_used = existing.get("tools_used")
+    if not isinstance(tools_used, list):
+        return []
+    return tools_used
+
+
+def _merge_tools_used(existing: list, family: str) -> list:
+    """Append `family` to `existing`, deduped, preserving first-seen order."""
+    if family in existing:
+        return list(existing)
+    return list(existing) + [family]
+
+
+def _test_delay() -> None:
+    """Test-only injection point: sleep inside the locked read-merge-write
+    section when `CODE_INTELLIGENCE_TURN_MARK_TEST_DELAY_MS` is set,
+    widening the race window so a concurrency test can deterministically
+    force two hook invocations to overlap on the same sentinel rather than
+    relying on real-world timing luck. Unset in production; a bad/missing
+    value is a no-op (fail-open)."""
+    delay_ms = os.environ.get("CODE_INTELLIGENCE_TURN_MARK_TEST_DELAY_MS")
+    if not delay_ms:
+        return
+    try:
+        time.sleep(int(delay_ms) / 1000)
+    except (ValueError, OSError):
+        pass
+
+
+@contextlib.contextmanager
+def _sentinel_lock(sentinel: Path):
+    """Exclusive advisory lock held for the full read-merge-write cycle.
+
+    Prevents the lost-update race where two concurrent PostToolUse
+    invocations (e.g. two MCP tool calls firing in quick succession) both
+    read the same stale `tools_used` list, merge in different families, and
+    one write clobbers the other's update. `fcntl.flock` on POSIX,
+    `msvcrt.locking` on Windows (this repo's hooks target both — see the
+    Windows note on `_write_sentinel_atomic`'s tempfile+rename above).
+
+    Fail-open: any failure to open/lock the lock file — missing `fcntl` and
+    `msvcrt` both, or an `OSError` opening it — falls through to running the
+    critical section unlocked rather than raising. A lost-update race under
+    that fallback is strictly worse than today's behavior (already racy)
+    but a crash is not; this hook is a nudge dependency, never a gate.
+    """
+    lock_path = sentinel.parent / (sentinel.name + ".lock")
+    try:
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        yield
+        return
+
+    # The `open()` failure case (fail-open: fall through to an unlocked
+    # critical section) has to share this try/except with the whole
+    # `with` body rather than wrapping only the open() call, since ruff's
+    # SIM115 requires `open()` to appear directly in a `with` statement.
+    # Every helper invoked between here and the `yield` already catches
+    # its own OSErrors (see _existing_tools_used/_write_sentinel_atomic),
+    # so this outer except only ever fires for the open() call itself.
+    try:
+        with open(lock_path, "a+") as fh:
+            locked = False
+            try:
+                try:
+                    if fcntl is not None:
+                        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+                        locked = True
+                    elif msvcrt is not None:
+                        fh.seek(0)
+                        msvcrt.locking(fh.fileno(), msvcrt.LK_LOCK, 1)
+                        locked = True
+                except OSError:
+                    locked = False
+                yield
+            finally:
+                if locked:
+                    try:
+                        if fcntl is not None:
+                            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+                        elif msvcrt is not None:
+                            fh.seek(0)
+                            msvcrt.locking(fh.fileno(), msvcrt.LK_UNLCK, 1)
+                    except OSError:
+                        pass
+            return
+    except OSError:
+        pass
+    yield
+
+
+def _write_sentinel_atomic(sentinel: Path, payload: dict) -> None:
+    """Atomic write via a tempfile in the same directory + rename.
+
+    Mirrors the .sh's `mktemp` + `mv -f` pattern so the nudge hook never sees
+    a partial JSON. Any failure short-circuits to a silent exit 0.
+    """
+    parent = sentinel.parent
+    try:
+        parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return
+
+    # NamedTemporaryFile with delete=False + explicit rename gives us the
+    # same atomic-mv semantic on macOS + Linux + Windows Git Bash.
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            prefix=".code-intelligence-turn-state.",
+            dir=str(parent),
+        )
+    except OSError:
+        return
+    tmp = Path(tmp_path)
+    try:
+        # jq -n produces two-space-indented pretty JSON with a trailing
+        # newline. Match that byte-for-byte: `json.dumps(..., indent=2)` uses
+        # ": " (space after colon) and "," between items — the exact shape jq
+        # emits — and we append the trailing `\n` jq always writes.
+        body = json.dumps(payload, indent=2)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(body)
+            fh.write("\n")
+        os.replace(tmp, sentinel)
+    except OSError:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+
+
+def main() -> int:
+    payload = read_stdin_json() or {}
+    if not payload:
+        return 0
+
+    tool_name = payload.get("tool_name") or ""
+    family = _tool_family(tool_name) if isinstance(tool_name, str) else None
+    if family is None:
+        return 0
+
+    transcript_path_str = payload.get("transcript_path") or ""
+    if not isinstance(transcript_path_str, str) or not transcript_path_str:
+        return 0
+    transcript_path = Path(transcript_path_str)
+    if not transcript_path.is_file():
+        return 0
+
+    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd())
+    sentinel = project_dir / SENTINEL_RELATIVE_PATH
+
+    tid = transcript_id(transcript_path_str)
+    tc = count_user_lines(transcript_path)
+
+    with _sentinel_lock(sentinel):
+        tools_used = _merge_tools_used(_existing_tools_used(sentinel, tid, tc), family)
+        _test_delay()
+        _write_sentinel_atomic(
+            sentinel,
+            {"transcript_id": tid, "turn_counter": tc, "tools_used": tools_used},
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # noqa: BLE001 - fail-open by design; this hook is a
+        # nudge, never a gate. Matches the module docstring's posture
+        # ("Any internal error -> exit 0") and the sibling nudge hook's
+        # identical guard.
+        sys.exit(0)