edit-guard 0.1.0__py3-none-any.whl

edit_guard/__init__.py

@@ -0,0 +1,3 @@
+"""edit-guard: block stale concurrent edits across agent sessions."""
+
+__version__ = "0.1.0"

edit_guard/cli.py

@@ -0,0 +1,198 @@
+"""edit-guard: a PreToolUse hook that blocks stale concurrent edits."""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+
+from . import guard
+
+
+def _hook_input():
+    """Read the hook's stdin JSON defensively."""
+    try:
+        raw = sys.stdin.read()
+        obj = json.loads(raw)
+        return obj if isinstance(obj, dict) else {}
+    except Exception:
+        return {}
+
+
+def _tool_path(tool_name, tool_input):
+    if not isinstance(tool_input, dict):
+        return None
+    for key in ("file_path", "path", "file", "filename"):
+        v = tool_input.get(key)
+        if v:
+            return os.path.abspath(os.path.expanduser(str(v)))
+    return None
+
+
+def cmd_hook(args):
+    """Entry point for the PreToolUse/PostToolUse hooks.
+
+    Exits 0 (allow) or 2 (block). PostToolUse (--post-write) only records
+    the post-write digest and never blocks.
+    """
+    try:
+        data = _hook_input()
+        tool = data.get("tool_name", "")
+        session = str(data.get("session_id", "") or "unknown")
+        if tool not in guard.WATCHED:
+            return 0
+        path = _tool_path(tool, data.get("tool_input"))
+        if not path:
+            return 0
+
+        if getattr(args, "post_write", False):
+            # PostToolUse: the write has landed; record the new digest so
+            # this session's next PreToolUse check sees its own change.
+            if tool in guard.WRITE_TOOLS:
+                guard.record(session, tool, path, guard.digest_of(path))
+            return 0
+
+        if tool in guard.READ_TOOLS or args.observe:
+            # Observe-only: record what this session saw, never block.
+            guard.record(session, tool, path, guard.digest_of(path))
+            return 0
+
+        allowed, reason = guard.check(session, path)
+        guard.record(session, tool, path, guard.digest_of(path))
+        if not allowed:
+            sys.stderr.write(reason + "\n")
+            return 2
+        return 0
+    except Exception:
+        return 0  # fail open, always
+
+
+def _settings_path():
+    return os.path.join(os.path.expanduser("~"), ".claude", "settings.json")
+
+
+HOOK_SNIPPET = {
+    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+    "hooks": [{"type": "command", "command": "edit-guard hook"}],
+}
+POST_SNIPPET = {
+    "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+    "hooks": [{"type": "command", "command": "edit-guard hook --post-write"}],
+}
+READ_SNIPPET = {
+    "matcher": "Read",
+    "hooks": [{"type": "command", "command": "edit-guard hook --observe"}],
+}
+ALL_SNIPPETS = (
+    ("PreToolUse", HOOK_SNIPPET),
+    ("PostToolUse", POST_SNIPPET),
+    ("PreToolUse", READ_SNIPPET),
+)
+
+
+def cmd_install(args):
+    """Merge the hook into ~/.claude/settings.json (with backup)."""
+    sp = _settings_path()
+    settings = {}
+    if os.path.exists(sp):
+        try:
+            with open(sp, "r", encoding="utf-8") as fh:
+                settings = json.load(fh)
+            if not isinstance(settings, dict):
+                settings = {}
+        except Exception as e:
+            print("Could not parse %s: %s" % (sp, e), file=sys.stderr)
+            return 1
+        bak = sp + ".bak"
+        try:
+            shutil.copy2(sp, bak)
+            print("Backed up %s -> %s" % (sp, bak))
+        except OSError as e:
+            print("Backup failed: %s" % e, file=sys.stderr)
+            return 1
+
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        hooks = {}
+        settings["hooks"] = hooks
+
+    def present(entries, snippet):
+        return any(
+            h.get("matcher") == snippet["matcher"]
+            and any("edit-guard" in (x.get("command", "") or "")
+                    for x in h.get("hooks", []))
+            for h in entries if isinstance(h, dict))
+
+    added = 0
+    for hook_type, snippet in ALL_SNIPPETS:
+        entries = hooks.get(hook_type)
+        if not isinstance(entries, list):
+            entries = []
+            hooks[hook_type] = entries
+        if present(entries, snippet):
+            continue
+        entries.append(snippet)
+        added += 1
+
+    os.makedirs(os.path.dirname(sp), exist_ok=True)
+    with open(sp, "w", encoding="utf-8") as fh:
+        json.dump(settings, fh, indent=2)
+        fh.write("\n")
+    print("Installed edit-guard hooks into %s (%d added, %d already present)."
+          % (sp, added, len(ALL_SNIPPETS) - added))
+    print("Restart Claude Code for the hooks to take effect.")
+    return 0
+
+
+def cmd_log(args):
+    entries = guard._read_log()
+    entries.sort(key=lambda e: e.get("ts", 0))
+    for e in entries[-args.limit:]:
+        import datetime
+        ts = datetime.datetime.fromtimestamp(e.get("ts", 0)).strftime("%m-%d %H:%M:%S")
+        print("%s  %-12s %-10s %s" % (
+            ts, str(e.get("session", ""))[:12],
+            e.get("tool", ""), e.get("path", "")))
+    return 0
+
+
+def cmd_status(args):
+    print("state dir: %s" % guard.state_dir())
+    print("log:       %s (%d entries)" % (guard.log_path(), len(guard._read_log())))
+    print("settings:  %s" % _settings_path())
+    return 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="edit-guard",
+        description="Block stale concurrent edits across agent sessions.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    ph = sub.add_parser("hook", help="Run as a Claude Code PreToolUse hook.")
+    ph.add_argument("--observe", action="store_true",
+                    help="Record only, never block (for Read).")
+    ph.add_argument("--post-write", action="store_true",
+                    help="PostToolUse mode: record the post-write digest, "
+                         "never block.")
+    ph.set_defaults(func=cmd_hook)
+
+    pi = sub.add_parser("install", help="Install into ~/.claude/settings.json.")
+    pi.set_defaults(func=cmd_install)
+
+    pl = sub.add_parser("log", help="Show recent guarded file events.")
+    pl.add_argument("--limit", type=int, default=20)
+    pl.set_defaults(func=cmd_log)
+
+    ps = sub.add_parser("status", help="Show state and config paths.")
+    ps.set_defaults(func=cmd_status)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

edit_guard/guard.py

@@ -0,0 +1,162 @@
+"""Core staleness-detection logic for edit-guard.
+
+Model: every Read/Edit/Write observed through the hooks records
+(session_id, tool, path, digest_seen, timestamp) in an append-only log.
+PreToolUse records the digest *before* a write; PostToolUse records the
+digest *after* the write lands. When a session attempts Edit/Write on a
+path, we compare the file's current digest against the digest *that session*
+last saw (usually its own post-write record). If the file changed since
+then AND another session *wrote* to it in between, the edit is stale and
+blocked. Another session's Read never counts as a modification.
+
+Everything fails open: any unexpected error means "allow".
+"""
+
+import hashlib
+import json
+import os
+import time
+
+WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+READ_TOOLS = {"Read"}
+WATCHED = WRITE_TOOLS | READ_TOOLS
+
+MAX_LOG_LINES = 20000
+PRUNE_KEEP = 10000
+MAX_HASH_BYTES = 50 * 1024 * 1024
+
+
+def state_dir():
+    return os.environ.get(
+        "EDIT_GUARD_DIR",
+        os.path.join(os.path.expanduser("~"), ".config", "edit-guard"))
+
+
+def log_path():
+    return os.path.join(state_dir(), "writes.jsonl")
+
+
+def digest_of(path):
+    """sha256 of file contents; falls back to mtime+size for huge files."""
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return None
+    try:
+        if size > MAX_HASH_BYTES:
+            st = os.stat(path)
+            return "stat:%d:%d" % (st.st_mtime_ns, st.st_size)
+        h = hashlib.sha256()
+        with open(path, "rb") as fh:
+            for chunk in iter(lambda: fh.read(65536), b""):
+                h.update(chunk)
+        return "sha256:" + h.hexdigest()
+    except OSError:
+        return None
+
+
+def _read_log():
+    """Return list of entry dicts; tolerate missing/corrupt log."""
+    entries = []
+    try:
+        fh = open(log_path(), "r", encoding="utf-8", errors="replace")
+    except OSError:
+        return entries
+    with fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except Exception:
+                continue
+            if isinstance(obj, dict) and obj.get("path"):
+                entries.append(obj)
+    return entries
+
+
+def _prune_if_needed():
+    p = log_path()
+    try:
+        with open(p, "r", encoding="utf-8") as fh:
+            lines = fh.readlines()
+    except OSError:
+        return
+    if len(lines) <= MAX_LOG_LINES:
+        return
+    try:
+        with open(p, "w", encoding="utf-8") as fh:
+            fh.writelines(lines[-PRUNE_KEEP:])
+    except OSError:
+        pass
+
+
+def record(session_id, tool, path, digest):
+    """Append an observation. Never raises."""
+    try:
+        os.makedirs(state_dir(), exist_ok=True)
+        entry = {"ts": time.time(), "session": session_id,
+                 "tool": tool, "path": path, "digest": digest}
+        with open(log_path(), "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry) + "\n")
+        _prune_if_needed()
+    except OSError:
+        pass
+
+
+def check(session_id, path):
+    """Decide whether session_id may write path right now.
+
+    Returns (allowed: bool, reason: str). Never raises.
+    """
+    try:
+        return _check_inner(session_id, path)
+    except Exception:
+        return True, ""  # fail open
+
+
+def _check_inner(session_id, path):
+    current = digest_of(path)
+    if current is None:
+        return True, ""  # new file or unreadable: nothing to be stale against
+
+    entries = [e for e in _read_log() if e.get("path") == path]
+
+    # Pass 1: my most recent observation of this path.
+    mine = None
+    for e in entries:
+        if e.get("session") == session_id:
+            if mine is None or e.get("ts", 0) > mine.get("ts", 0):
+                mine = e
+
+    if mine is None:
+        # I have never seen this file; someone else may have. First write
+        # is allowed (MVP does not track pre-read staleness for writers
+        # who never read through the hook), but we record it.
+        return True, ""
+
+    if mine.get("digest") == current:
+        return True, ""  # unchanged since I last saw it
+
+    # Pass 2: another session's *write* newer than my last observation.
+    # Reads can never modify the file, so they are not blame candidates.
+    other_newer = None
+    for e in entries:
+        if e.get("session") == session_id:
+            continue
+        if e.get("tool") not in WRITE_TOOLS:
+            continue
+        if e.get("ts", 0) > mine.get("ts", 0):
+            if other_newer is None or e.get("ts", 0) > other_newer.get("ts", 0):
+                other_newer = e
+
+    if other_newer is not None:
+        other = other_newer.get("session", "another session")
+        return (False,
+                "Stale edit blocked: '%s' changed since you last saw it "
+                "(last modified by session '%s'). Re-read the file before "
+                "editing." % (path, other))
+    # Changed, but only by me (e.g. external tool or my own earlier write
+    # that raced the log): allow, this session's assumptions are its own.
+    return True, ""

edit_guard-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: edit-guard
+Version: 0.1.0
+Summary: A Claude Code PreToolUse hook that blocks stale concurrent edits across agent sessions
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/edit-guard
+Keywords: claude-code,hooks,concurrency,developer-tools,agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# edit-guard
+
+A tiny [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hook that
+stops one agent session from editing a file another session changed
+underneath it.
+
+The failure mode, quoted from a real-world report: *"With several agent
+sessions on one repository, session A reads `createSession`, session B
+changes it, and A then edits on the old assumption."* edit-guard watches every
+`Read`/`Edit`/`Write` through the hook, remembers what each session last saw,
+and blocks the write when the file moved on without you — telling the agent to
+re-read first.
+
+Zero dependencies. Python standard library only. Everything stays local.
+
+## Install
+
+```bash
+git clone https://github.com/hahahahahahahahah6/edit-guard
+cd edit-guard
+pip install .
+edit-guard install
+```
+
+`install` merges three hook entries into `~/.claude/settings.json` (backing it up
+first, never clobbering your existing settings):
+
+- `PreToolUse` on `Edit|Write|MultiEdit|NotebookEdit` → `edit-guard hook` (may block)
+- `PostToolUse` on `Edit|Write|MultiEdit|NotebookEdit` → `edit-guard hook --post-write`
+  (records the digest *after* your write, never blocks — this is what keeps
+  your own consecutive edits from looking stale)
+- `PreToolUse` on `Read` → `edit-guard hook --observe` (records what you saw, never blocks)
+
+Restart Claude Code afterwards. That's it — no MCP server, no daemon, no
+accounts.
+
+## How it works
+
+Each hook invocation appends one line to `~/.config/edit-guard/writes.jsonl`:
+`{session_id, tool, path, digest_seen, timestamp}`. When a session tries to
+write a file:
+
+1. Hash the file's current content (sha256; mtime+size for files over 50 MB).
+2. Compare against the digest **that session** last saw for that path.
+3. If it changed **and** another session touched the file in between → block
+   (exit 2) with: *"Stale edit blocked: '…' changed since you last saw it
+   (last modified by session '…'). Re-read the file before editing."*
+
+Same-session rewrites, new files, and files only you touched are always
+allowed. The hook **fails open**: any internal error (corrupt log, unreadable
+file, malformed input) means "allow".
+
+Inspect what's being tracked:
+
+```bash
+edit-guard log            # recent guarded file events
+edit-guard status         # state dir / log / settings paths
+```
+
+## Honest limitations
+
+- **Write-after-write staleness only.** The guard compares against what your
+  session last *saw through the hook*. Edits made outside any hooked session
+  (your editor, a script) are treated as your own session's drift and allowed.
+- **Not a lock.** This is advisory staleness detection, not mutual exclusion.
+  Two sessions can still race within the same second; the loser is blocked,
+  the winner wins.
+- **Digest, not semantics.** A reformat that changes bytes but not meaning
+  still counts as "changed" and can block you. Re-read and retry.
+- **Hook protocol is undocumented.** The PreToolUse stdin shape (`session_id`,
+  `tool_name`, `tool_input`) and the exit-2-blocks convention come from
+  community documentation, not a stable API. If Claude Code changes the
+  protocol, the hook degrades to fail-open allow.
+- **Per-machine only.** Sessions on different machines don't share the log.
+- The log is append-only with light pruning (keeps the last 10k of 20k lines);
+  it is not a backup or audit trail.
+
+## Development
+
+```bash
+python3 tests/test_guard.py
+```
+
+## License
+
+MIT

edit_guard-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+edit_guard/__init__.py,sha256=aCzHR5t9xZVMk6fqjxqz5517kL0JpBrPiuKXDIsyiaw,93
+edit_guard/cli.py,sha256=T61HZjFpGLUPMf-uJz0hmzzIDnHdOEdsCRB3YiizZeE,6212
+edit_guard/guard.py,sha256=cIMx7lYrjH5Gule9uMVteFzMiJm1KGspL6a8mkI_yKo,5122
+edit_guard-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+edit_guard-0.1.0.dist-info/METADATA,sha256=JAFD-08nPAYWOwhsMSehcX0_LMIJnBcT2rMVqiYS1yg,3839
+edit_guard-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+edit_guard-0.1.0.dist-info/entry_points.txt,sha256=TEa2bmkYloKaMWKHevTSTe5Y_xZxkicOdpcRqzqB3Y4,51
+edit_guard-0.1.0.dist-info/top_level.txt,sha256=qQnoq-OnEucdBcojbifTtXBTP1NuSrc25d5e0Y9WBsQ,11
+edit_guard-0.1.0.dist-info/RECORD,,

edit_guard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

edit_guard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+edit-guard = edit_guard.cli:main

edit_guard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edit_guard-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+edit_guard