history-graph-protocol 0.2.0__tar.gz

history_graph_protocol-0.2.0/.claude/hooks/post_bash_hgp.py

@@ -0,0 +1,78 @@
+"""PostToolUse hook for Bash: detect and report actual file changes after Bash commands.
+
+Only runs git status when the Pre-Bash hook wrote a marker file indicating a
+potentially mutating command was about to execute. This avoids the overhead of
+git status on every read-only Bash call.
+
+Known limitation: .gitignore'd files won't appear in the report.
+
+Marker file: /tmp/.hgp_bash_mutating_<ppid>
+"""
+import json
+import os
+import subprocess
+import sys
+
+_TIMEOUT_SECS = 2
+
+
+def _marker_path() -> str:
+    return f"/tmp/.hgp_bash_mutating_{os.getppid()}"
+
+
+def _consume_marker() -> bool:
+    """Return True and remove marker if it exists, False otherwise."""
+    path = _marker_path()
+    try:
+        os.unlink(path)
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _git_changed_files(cwd: str) -> list[str]:
+    """Run git status --porcelain and return list of changed file entries."""
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT_SECS,
+        )
+        if result.returncode != 0:
+            return []
+        lines = [l for l in result.stdout.splitlines() if l.strip()]
+        return lines
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    if event.get("tool_name") != "Bash":
+        sys.exit(0)
+
+    if not _consume_marker():
+        # No marker → Pre hook didn't flag this as mutating; skip git status
+        sys.exit(0)
+
+    cwd = os.getcwd()
+    changed = _git_changed_files(cwd)
+    if not changed:
+        sys.exit(0)
+
+    lines_str = "\n  ".join(changed)
+    print(
+        f"[HGP] Bash command changed tracked files (use hgp_* tools for history):\n  {lines_str}",
+        file=sys.stderr,
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.claude/hooks/pre_bash_hgp.py

@@ -0,0 +1,138 @@
+"""PreToolUse hook for Bash: warn when shell commands may mutate files outside HGP.
+
+This hook is non-blocking (always exit 0). It prints a warning to stderr when
+it detects shell patterns that typically write or delete files, reminding the
+agent to use hgp_* tools for tracked file operations.
+
+When a mutating pattern is detected, a marker file is written to /tmp so the
+Post-Bash hook can run 'git status' to report actual changes.
+
+Marker file: /tmp/.hgp_bash_mutating_<ppid>
+"""
+import json
+import os
+import re
+import sys
+
+# ── Read-only command prefixes — skip pattern matching for these ──────────────
+_READONLY_PREFIXES = (
+    "git log",
+    "git status",
+    "git diff",
+    "git show",
+    "git branch",
+    "git tag",
+    "git remote",
+    "git fetch",
+    "git ls",
+    "git stash list",
+    "ls ",
+    "ls\t",
+    "head ",
+    "tail ",
+    "grep ",
+    "rg ",
+    "find ",
+    "wc ",
+    "diff ",
+    "less ",
+    "more ",
+    "file ",
+    "stat ",
+    "pwd",
+    "date",
+    "which ",
+    "type ",
+    "uname",
+)
+
+# ── Mutating patterns (regex) ─────────────────────────────────────────────────
+_HIGH_PATTERNS = [
+    re.compile(r"\bcp\b"),
+    re.compile(r"\bmv\b"),
+    re.compile(r"\brm\b"),
+    re.compile(r"\btee\b"),
+    re.compile(r"\btouch\b"),
+    re.compile(r"\binstall\b"),
+    re.compile(r"\bmkdir\b"),
+    re.compile(r"\brmdir\b"),
+    re.compile(r"\bchmod\b"),
+    re.compile(r"\bchown\b"),
+    re.compile(r"\bln\b"),
+    re.compile(r"\btruncate\b"),
+    # git commands that rewrite working-tree files
+    re.compile(r"\bgit\s+checkout\b"),
+    re.compile(r"\bgit\s+restore\b"),
+    re.compile(r"\bgit\s+switch\b"),
+    re.compile(r"\bgit\s+apply\b"),
+    re.compile(r"\bgit\s+revert\b"),
+    re.compile(r"\bgit\s+merge\b"),
+    re.compile(r"\bgit\s+rebase\b"),
+    re.compile(r"\bgit\s+reset\b"),
+    # patch tools
+    re.compile(r"\bpatch\b"),
+]
+
+_MEDIUM_PATTERNS = [
+    re.compile(r"(?<![|&])\s*>(?!>)"),  # stdout redirect (not >>)
+    re.compile(r">>"),                   # append redirect
+    re.compile(r"\bsed\s+-i\b"),
+    re.compile(r"\bdd\b"),
+    re.compile(r"\bawk\b.*>"),           # awk with redirect
+]
+
+
+def _is_readonly(command: str) -> bool:
+    stripped = command.lstrip()
+    return any(stripped.startswith(p) for p in _READONLY_PREFIXES)
+
+
+def _detect_mutating(command: str) -> str | None:
+    """Return the first matched pattern description, or None if command looks safe."""
+    for pat in _HIGH_PATTERNS:
+        if pat.search(command):
+            return pat.pattern
+    for pat in _MEDIUM_PATTERNS:
+        if pat.search(command):
+            return pat.pattern
+    return None
+
+
+def _marker_path() -> str:
+    return f"/tmp/.hgp_bash_mutating_{os.getppid()}"
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    if event.get("tool_name") != "Bash":
+        sys.exit(0)
+
+    command: str = event.get("tool_input", {}).get("command", "")
+    if not command or _is_readonly(command):
+        sys.exit(0)
+
+    matched = _detect_mutating(command)
+    if matched is None:
+        sys.exit(0)
+
+    # Write marker so Post-Bash hook knows to run git status
+    try:
+        open(_marker_path(), "w").close()
+    except OSError:
+        pass  # /tmp not writable — skip gating, hook still warns
+
+    print(
+        f"[HGP] Bash command may mutate files (matched: {matched!r}). "
+        "If this writes or deletes tracked files, prefer hgp_* tools so the "
+        "operation is recorded in HGP history.",
+        file=sys.stderr,
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.claude/hooks/pre_tool_use_hgp.py

@@ -0,0 +1,46 @@
+"""PreToolUse hook: warn when native Write/Edit is used instead of hgp_* tools.
+
+Exit 0 = allow the tool call (non-blocking by default).
+Print to stderr = message shown to the agent as a warning.
+Set HGP_HOOK_BLOCK=1 to make the hook reject native file tool calls.
+"""
+import json
+import os
+import sys
+
+HGP_TOOLS = {
+    "Write": "hgp_write_file",
+    "Edit": "hgp_edit_file",
+    "MultiEdit": "hgp_edit_file",
+}
+
+BLOCK_MODE = os.environ.get("HGP_HOOK_BLOCK", "0") == "1"
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = event.get("tool_name", "")
+    if tool_name not in HGP_TOOLS:
+        sys.exit(0)
+
+    hgp_equiv = HGP_TOOLS[tool_name]
+    msg = (
+        f"[HGP] Native `{tool_name}` detected. "
+        f"Use `{hgp_equiv}` instead to record this file operation in HGP history. "
+        f"Set HGP_HOOK_BLOCK=1 to enforce this as an error."
+    )
+    print(msg, file=sys.stderr)
+
+    if BLOCK_MODE:
+        # Exit 2 = block; Claude Code reads stderr (already printed above), ignores stdout
+        sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/pre_tool_use_hgp.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/pre_bash_hgp.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/post_bash_hgp.py"
+          }
+        ]
+      }
+    ]
+  }
+}

history_graph_protocol-0.2.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(git:*)",
+      "Bash(python -m pytest tests/test_file_ops.py tests/test_project.py tests/test_db.py -v --tb=short)",
+      "WebSearch",
+      "WebFetch(domain:geminicli.com)",
+      "WebFetch(domain:github.com)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs"
+    ]
+  }
+}

history_graph_protocol-0.2.0/.gemini/hooks/post_bash_hgp.py

@@ -0,0 +1,82 @@
+"""AfterTool hook for Gemini CLI: detect and report actual file changes after shell commands.
+
+Only runs git status when the BeforeTool hook wrote a marker file indicating a
+potentially mutating command was about to execute. This avoids the overhead of
+git status on every read-only shell call.
+
+Gemini CLI protocol (always exit 0):
+  Report:       stdout JSON {"systemMessage": "..."}
+  Pass-through: no stdout output
+
+Known limitation: .gitignore'd files won't appear in the report.
+
+Marker file: /tmp/.hgp_bash_mutating_<ppid>
+"""
+import json
+import os
+import subprocess
+import sys
+
+_TIMEOUT_SECS = 2
+
+
+def _marker_path() -> str:
+    return f"/tmp/.hgp_bash_mutating_{os.getppid()}"
+
+
+def _consume_marker() -> bool:
+    """Return True and remove marker if it exists, False otherwise."""
+    path = _marker_path()
+    try:
+        os.unlink(path)
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _git_changed_files(cwd: str) -> list[str]:
+    """Run git status --porcelain and return list of changed file entries."""
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT_SECS,
+        )
+        if result.returncode != 0:
+            return []
+        lines = [l for l in result.stdout.splitlines() if l.strip()]
+        return lines
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    if event.get("tool_name") != "shell":
+        sys.exit(0)
+
+    if not _consume_marker():
+        # No marker → BeforeTool hook didn't flag this as mutating; skip git status
+        sys.exit(0)
+
+    cwd = os.getcwd()
+    changed = _git_changed_files(cwd)
+    if not changed:
+        sys.exit(0)
+
+    lines_str = "\n  ".join(changed)
+    msg = (
+        f"[HGP] Bash command changed tracked files (use hgp_* tools for history):\n  {lines_str}"
+    )
+    print(json.dumps({"systemMessage": msg}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.gemini/hooks/pre_bash_hgp.py

@@ -0,0 +1,138 @@
+"""BeforeTool hook for Gemini CLI: warn when Bash commands may mutate files outside HGP.
+
+Gemini CLI protocol (always exit 0):
+  Warn:         stdout JSON {"systemMessage": "..."}
+  Pass-through: no stdout output
+
+When a mutating pattern is detected, a marker file is written to /tmp so the
+AfterTool hook can run 'git status' to report actual changes.
+
+Marker file: /tmp/.hgp_bash_mutating_<ppid>
+"""
+import json
+import os
+import re
+import sys
+
+# ── Read-only command prefixes — skip pattern matching for these ──────────────
+_READONLY_PREFIXES = (
+    "git log",
+    "git status",
+    "git diff",
+    "git show",
+    "git branch",
+    "git tag",
+    "git remote",
+    "git fetch",
+    "git ls",
+    "git stash list",
+    "ls ",
+    "ls\t",
+    "head ",
+    "tail ",
+    "grep ",
+    "rg ",
+    "find ",
+    "wc ",
+    "diff ",
+    "less ",
+    "more ",
+    "file ",
+    "stat ",
+    "pwd",
+    "date",
+    "which ",
+    "type ",
+    "uname",
+)
+
+# ── Mutating patterns (regex) ─────────────────────────────────────────────────
+_HIGH_PATTERNS = [
+    re.compile(r"\bcp\b"),
+    re.compile(r"\bmv\b"),
+    re.compile(r"\brm\b"),
+    re.compile(r"\btee\b"),
+    re.compile(r"\btouch\b"),
+    re.compile(r"\binstall\b"),
+    re.compile(r"\bmkdir\b"),
+    re.compile(r"\brmdir\b"),
+    re.compile(r"\bchmod\b"),
+    re.compile(r"\bchown\b"),
+    re.compile(r"\bln\b"),
+    re.compile(r"\btruncate\b"),
+    # git commands that rewrite working-tree files
+    re.compile(r"\bgit\s+checkout\b"),
+    re.compile(r"\bgit\s+restore\b"),
+    re.compile(r"\bgit\s+switch\b"),
+    re.compile(r"\bgit\s+apply\b"),
+    re.compile(r"\bgit\s+revert\b"),
+    re.compile(r"\bgit\s+merge\b"),
+    re.compile(r"\bgit\s+rebase\b"),
+    re.compile(r"\bgit\s+reset\b"),
+    # patch tools
+    re.compile(r"\bpatch\b"),
+]
+
+_MEDIUM_PATTERNS = [
+    re.compile(r"(?<![|&])\s*>(?!>)"),  # stdout redirect (not >>)
+    re.compile(r">>"),                   # append redirect
+    re.compile(r"\bsed\s+-i\b"),
+    re.compile(r"\bdd\b"),
+    re.compile(r"\bawk\b.*>"),           # awk with redirect
+]
+
+
+def _is_readonly(command: str) -> bool:
+    stripped = command.lstrip()
+    return any(stripped.startswith(p) for p in _READONLY_PREFIXES)
+
+
+def _detect_mutating(command: str) -> str | None:
+    """Return the first matched pattern description, or None if command looks safe."""
+    for pat in _HIGH_PATTERNS:
+        if pat.search(command):
+            return pat.pattern
+    for pat in _MEDIUM_PATTERNS:
+        if pat.search(command):
+            return pat.pattern
+    return None
+
+
+def _marker_path() -> str:
+    return f"/tmp/.hgp_bash_mutating_{os.getppid()}"
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    if event.get("tool_name") != "shell":
+        sys.exit(0)
+
+    command: str = event.get("tool_input", {}).get("command", "")
+    if not command or _is_readonly(command):
+        sys.exit(0)
+
+    matched = _detect_mutating(command)
+    if matched is None:
+        sys.exit(0)
+
+    # Write marker so AfterTool hook knows to run git status
+    try:
+        open(_marker_path(), "w").close()
+    except OSError:
+        pass  # /tmp not writable — skip gating, hook still warns
+
+    msg = (
+        f"[HGP] Bash command may mutate files (matched: {matched!r}). "
+        "If this writes or deletes tracked files, prefer hgp_* tools so the "
+        "operation is recorded in HGP history."
+    )
+    print(json.dumps({"systemMessage": msg}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.gemini/hooks/pre_tool_use_hgp.py

@@ -0,0 +1,48 @@
+"""BeforeTool hook for Gemini CLI: warn/block when native file tools are used.
+
+Gemini CLI protocol (all responses exit 0):
+  Warn mode (default):   stdout JSON {"systemMessage": "..."}
+  Block mode (HGP_HOOK_BLOCK=1): stdout JSON {"decision": "deny", "reason": "..."}
+  Pass-through:          no stdout output
+
+Set HGP_HOOK_BLOCK=1 to enforce blocking instead of warning.
+"""
+import json
+import os
+import sys
+
+HGP_TOOLS = {
+    "write_file": "hgp_write_file",
+    "replace": "hgp_edit_file",
+}
+
+BLOCK_MODE = os.environ.get("HGP_HOOK_BLOCK", "0") == "1"
+
+
+def main() -> None:
+    try:
+        event = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = event.get("tool_name", "")
+    if tool_name not in HGP_TOOLS:
+        sys.exit(0)
+
+    hgp_equiv = HGP_TOOLS[tool_name]
+    msg = (
+        f"[HGP] Native `{tool_name}` detected. "
+        f"Use `{hgp_equiv}` instead to record this file operation in HGP history. "
+        f"Set HGP_HOOK_BLOCK=1 to enforce this as an error."
+    )
+
+    if BLOCK_MODE:
+        print(json.dumps({"decision": "deny", "reason": msg}))
+    else:
+        print(json.dumps({"systemMessage": msg}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

history_graph_protocol-0.2.0/.gemini/settings.json

@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "^(write_file|replace)$",
+        "hooks": [
+          {
+            "name": "hgp-enforcement",
+            "type": "command",
+            "command": "python3 .gemini/hooks/pre_tool_use_hgp.py"
+          }
+        ]
+      },
+      {
+        "matcher": "^shell$",
+        "hooks": [
+          {
+            "name": "hgp-bash-pre",
+            "type": "command",
+            "command": "python3 .gemini/hooks/pre_bash_hgp.py"
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "matcher": "^shell$",
+        "hooks": [
+          {
+            "name": "hgp-bash-post",
+            "type": "command",
+            "command": "python3 .gemini/hooks/post_bash_hgp.py"
+          }
+        ]
+      }
+    ]
+  }
+}

history_graph_protocol-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+# HGP repo-local storage (not committed to git)
+.hgp/
+*.db-wal
+*.db-shm
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.worktrees/
+SESSION_HANDOVER.md

history_graph_protocol-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12