edit-guard 0.1.0__tar.gz

edit_guard-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,86 @@
+# 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/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "edit-guard"
+version = "0.1.0"
+description = "A Claude Code PreToolUse hook that blocks stale concurrent edits across agent sessions"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "hao li" }]
+keywords = ["claude-code", "hooks", "concurrency", "developer-tools", "agents"]
+
+[project.scripts]
+edit-guard = "edit_guard.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/edit-guard"
+
+[tool.setuptools.packages.find]
+where = ["src"]

edit_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

edit_guard-0.1.0/src/edit_guard/__init__.py

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

edit_guard-0.1.0/src/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-0.1.0/src/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/src/edit_guard.egg-info/PKG-INFO

@@ -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/src/edit_guard.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/edit_guard/__init__.py
+src/edit_guard/cli.py
+src/edit_guard/guard.py
+src/edit_guard.egg-info/PKG-INFO
+src/edit_guard.egg-info/SOURCES.txt
+src/edit_guard.egg-info/dependency_links.txt
+src/edit_guard.egg-info/entry_points.txt
+src/edit_guard.egg-info/top_level.txt
+tests/test_guard.py

edit_guard-0.1.0/src/edit_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

edit_guard-0.1.0/src/edit_guard.egg-info/entry_points.txt

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

edit_guard-0.1.0/src/edit_guard.egg-info/top_level.txt

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

edit_guard-0.1.0/tests/test_guard.py

@@ -0,0 +1,194 @@
+"""Smoke tests for edit-guard: staleness detection across fake sessions."""
+
+import io
+import json
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from edit_guard import guard, cli  # noqa: E402
+
+
+def fresh_env():
+    tmp = tempfile.mkdtemp()
+    os.environ["EDIT_GUARD_DIR"] = os.path.join(tmp, "state")
+    return tmp
+
+
+def write_file(path, text):
+    with open(path, "w") as fh:
+        fh.write(text)
+
+
+def hook_stdin(session, tool, path):
+    return json.dumps({"session_id": session, "tool_name": tool,
+                       "tool_input": {"file_path": path}})
+
+
+def run_hook(stdin_text, observe=False, post_write=False):
+    old_stdin, old_stderr = sys.stdin, sys.stderr
+    sys.stdin = io.StringIO(stdin_text)
+    sys.stderr = io.StringIO()
+    try:
+        rc = cli.cmd_hook(
+            type("A", (), {"observe": observe, "post_write": post_write})())
+        err = sys.stderr.getvalue()
+    finally:
+        sys.stdin, sys.stderr = old_stdin, old_stderr
+    return rc, err
+
+
+def do_edit(session, f, new_text):
+    """Simulate the full hook cycle: PreToolUse -> write -> PostToolUse."""
+    rc, err = run_hook(hook_stdin(session, "Edit", f))
+    assert rc == 0, "pre-edit unexpectedly blocked: %s" % err
+    write_file(f, new_text)
+    rc, _ = run_hook(hook_stdin(session, "Edit", f), post_write=True)
+    assert rc == 0, "post-write hook should never block"
+    return rc
+
+
+def test_cross_session_stale_write_blocked():
+    tmp = fresh_env()
+    f = os.path.join(tmp, "shared.py")
+    write_file(f, "v1")
+    assert run_hook(hook_stdin("sess-A", "Read", f), observe=True)[0] == 0
+    do_edit("sess-B", f, "v2")  # B's edit lands via the full hook cycle
+    # A now tries to edit without re-reading: B's write is newer than A's read.
+    rc, err = run_hook(hook_stdin("sess-A", "Edit", f))
+    assert rc == 2, "expected block, got %d" % rc
+    assert "Stale edit blocked" in err
+    assert "sess-B" in err  # the writer is correctly blamed
+    print("cross-session stale blocked ok")
+
+
+def test_same_session_rewrite_allowed():
+    tmp = fresh_env()
+    f = os.path.join(tmp, "mine.py")
+    write_file(f, "v1")
+    assert run_hook(hook_stdin("sess-A", "Read", f), observe=True)[0] == 0
+    do_edit("sess-A", f, "v2")
+    # Second edit: my post-write digest matches current -> allowed directly.
+    rc, err = run_hook(hook_stdin("sess-A", "Edit", f))
+    assert rc == 0, "own second edit blocked: %s" % err
+    print("same-session rewrite ok")
+
+
+def test_read_then_write_no_external_change():
+    tmp = fresh_env()
+    f = os.path.join(tmp, "calm.py")
+    write_file(f, "v1")
+    assert run_hook(hook_stdin("sess-A", "Read", f), observe=True)[0] == 0
+    rc, _ = run_hook(hook_stdin("sess-A", "Edit", f))
+    assert rc == 0
+    print("read-then-write ok")
+
+
+def test_new_file_write_allowed():
+    tmp = fresh_env()
+    f = os.path.join(tmp, "brand-new.py")  # does not exist
+    rc, _ = run_hook(hook_stdin("sess-A", "Write", f))
+    assert rc == 0
+    print("new file ok")
+
+
+def test_corrupt_log_fails_open():
+    tmp = fresh_env()
+    os.makedirs(os.environ["EDIT_GUARD_DIR"], exist_ok=True)
+    with open(guard.log_path(), "w") as fh:
+        fh.write("garbage{{{\nnot json\n")
+    f = os.path.join(tmp, "x.py")
+    write_file(f, "v1")
+    rc, _ = run_hook(hook_stdin("sess-A", "Edit", f))
+    assert rc == 0
+    print("corrupt log fail-open ok")
+
+
+def test_malformed_stdin_fails_open():
+    fresh_env()
+    rc, _ = run_hook("this is not json at all")
+    assert rc == 0
+    rc, _ = run_hook("{}")
+    assert rc == 0
+    print("malformed stdin ok")
+
+
+def test_install_merges_without_clobbering():
+    tmp = fresh_env()
+    fake_home = os.path.join(tmp, "home")
+    os.makedirs(os.path.join(fake_home, ".claude"))
+    sp = os.path.join(fake_home, ".claude", "settings.json")
+    with open(sp, "w") as fh:
+        json.dump({"theme": "dark", "hooks": {"PreToolUse": [
+            {"matcher": "Bash", "hooks": [{"type": "command", "command": "my-check"}]}
+        ]}}, fh)
+    old_home = os.environ.get("HOME")
+    os.environ["HOME"] = fake_home
+    try:
+        rc = cli.cmd_install(type("A", (), {})())
+        assert rc == 0
+        settings = json.load(open(sp))
+        assert settings["theme"] == "dark"  # untouched
+        matchers = [h["matcher"] for h in settings["hooks"]["PreToolUse"]]
+        assert "Bash" in matchers
+        assert "Edit|Write|MultiEdit|NotebookEdit" in matchers
+        assert "Read" in matchers
+        # idempotent: second install adds nothing
+        rc = cli.cmd_install(type("A", (), {})())
+        assert rc == 0
+        settings = json.load(open(sp))
+        # PreToolUse: original Bash entry + edit-guard Edit + edit-guard Read
+        assert len(settings["hooks"]["PreToolUse"]) == 3
+        # PostToolUse: edit-guard post-write entry
+        assert len(settings["hooks"]["PostToolUse"]) == 1
+        assert "--post-write" in settings["hooks"]["PostToolUse"][0]["hooks"][0]["command"]
+    finally:
+        if old_home is not None:
+            os.environ["HOME"] = old_home
+    print("install merge ok")
+
+
+def test_other_session_read_never_blocks():
+    # Regression: session B only READS the file. Session A edits twice in a
+    # row. The second edit must be allowed -- a Read cannot modify the file,
+    # so B must never be blamed for a stale edit.
+    tmp = fresh_env()
+    f = os.path.join(tmp, "shared2.py")
+    write_file(f, "v1")
+    assert run_hook(hook_stdin("sess-B", "Read", f), observe=True)[0] == 0
+    do_edit("sess-A", f, "v2")  # A's first edit lands via the full cycle
+    assert run_hook(hook_stdin("sess-B", "Read", f), observe=True)[0] == 0
+    # A's post-write digest matches current -> allowed, B not blamed.
+    rc, err = run_hook(hook_stdin("sess-A", "Edit", f))
+    assert rc == 0, "second edit by same session wrongly blocked: %s" % err
+    assert "sess-B" not in err
+    print("other-session read never blocks ok")
+
+
+def test_post_write_hook_never_blocks_and_records():
+    # The PostToolUse hook records the post-write digest and always exits 0.
+    tmp = fresh_env()
+    f = os.path.join(tmp, "post.py")
+    write_file(f, "v1")
+    rc, _ = run_hook(hook_stdin("sess-A", "Edit", f), post_write=True)
+    assert rc == 0
+    entries = [e for e in guard._read_log()
+               if e.get("session") == "sess-A" and e.get("path") == f]
+    assert len(entries) == 1
+    assert entries[0]["digest"] == guard.digest_of(f)
+    print("post-write hook ok")
+
+
+if __name__ == "__main__":
+    test_other_session_read_never_blocks()
+    test_cross_session_stale_write_blocked()
+    test_same_session_rewrite_allowed()
+    test_read_then_write_no_external_change()
+    test_new_file_write_allowed()
+    test_corrupt_log_fails_open()
+    test_malformed_stdin_fails_open()
+    test_install_merges_without_clobbering()
+    test_post_write_hook_never_blocks_and_records()
+    print("ALL EDIT-GUARD TESTS PASSED")