gitvow 0.4.0__tar.gz → 0.6.0__tar.gz

{gitvow-0.4.0/src/gitvow.egg-info → gitvow-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.4.0
+Version: 0.6.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.4.0 → gitvow-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.4.0"
+version = "0.6.0"
 description = "Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies."
 readme = "README.md"
 license = {text = "Apache-2.0"}

gitvow-0.6.0/src/gitvow/adapters.py

@@ -0,0 +1,155 @@
+"""Adapters: translate other agents' hook payloads into the Claude Code shape gitvow's handlers understand,
+and render decisions in each agent's native form. See docs/reference/adapters.md."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+AGENTS = ("claude", "codex", "gemini", "cursor")
+
+# agent event -> gitvow handler
+EVENT_MAP: dict[str, dict[str, str]] = {
+    "claude": {
+        "SessionStart": "SessionStart",
+        "PreToolUse": "PreToolUse",
+        "PostToolUse": "PostToolUse",
+        "Stop": "Stop",
+    },
+    "codex": {"SessionStart": "SessionStart", "PreToolUse": "PreToolUse", "PostToolUse": "PostToolUse", "Stop": "Stop"},
+    "gemini": {
+        "SessionStart": "SessionStart",
+        "BeforeTool": "PreToolUse",
+        "AfterTool": "PostToolUse",
+        "SessionEnd": "Stop",
+    },
+    "cursor": {
+        "sessionStart": "SessionStart",
+        "preToolUse": "PreToolUse",
+        "beforeShellExecution": "PreToolUse",
+        "beforeMCPExecution": "PreToolUse",
+        "afterFileEdit": "PostToolUse",
+        "afterShellExecution": "PostToolUse",
+        "stop": "Stop",
+    },
+}
+
+GEMINI_TOOLS = {"run_shell_command": "Bash", "write_file": "Write", "replace": "Edit", "edit": "Edit"}
+PATCH_FILE_RE = re.compile(r"^\*\*\* (Update|Add|Delete) File: (.+)$")
+
+
+def parse_apply_patch(text: str) -> list[dict[str, str]]:
+    """Codex apply_patch text -> [{file_path, old_string, new_string, op}] per touched file."""
+    files: list[dict[str, str]] = []
+    cur: dict[str, Any] | None = None
+    for line in (text or "").splitlines():
+        m = PATCH_FILE_RE.match(line.strip())
+        if m:
+            cur = {"op": m.group(1).lower(), "file_path": m.group(2).strip(), "old": [], "new": []}
+            files.append(cur)
+            continue
+        if cur is None or line.startswith("*** "):
+            continue
+        if line.startswith("+"):
+            cur["new"].append(line[1:])
+        elif line.startswith("-"):
+            cur["old"].append(line[1:])
+    return [
+        {
+            "file_path": f["file_path"],
+            "op": f["op"],
+            "old_string": "\n".join(f["old"]),
+            "new_string": "\n".join(f["new"]),
+        }
+        for f in files
+    ]
+
+
+def normalize(agent: str, event: str, payload: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
+    """Return one or more (gitvow_event, claude_shaped_payload). Codex patches expand to one Edit per file."""
+    if agent not in AGENTS:
+        raise ValueError(f"unknown agent {agent}")
+    gv_event = EVENT_MAP[agent].get(event)
+    if not gv_event:
+        return []
+    base = {
+        "session_id": payload.get("session_id") or payload.get("conversation_id") or "",
+        "transcript_path": payload.get("transcript_path") or "",
+        "cwd": payload.get("cwd") or (payload.get("workspace_roots") or [None])[0] or "",
+        "hook_event_name": gv_event,
+        "agent": agent,
+    }
+    if gv_event in ("SessionStart", "Stop"):
+        return [(gv_event, base)]
+    tool = str(payload.get("tool_name") or "")
+    inp = dict(payload.get("tool_input") or {})
+    if agent == "codex":
+        if tool == "apply_patch":
+            out = []
+            for f in parse_apply_patch(str(inp.get("command") or inp.get("patch") or "")):
+                out.append(
+                    (
+                        gv_event,
+                        {
+                            **base,
+                            "tool_name": "Edit",
+                            "tool_input": {
+                                "file_path": f["file_path"],
+                                "old_string": f["old_string"],
+                                "new_string": f["new_string"],
+                                "apply_patch_op": f["op"],
+                            },
+                        },
+                    )
+                )
+            return out or [(gv_event, {**base, "tool_name": "Edit", "tool_input": {}})]
+        return [(gv_event, {**base, "tool_name": tool, "tool_input": inp})]
+    if agent == "gemini":
+        return [(gv_event, {**base, "tool_name": GEMINI_TOOLS.get(tool, tool), "tool_input": inp})]
+    if agent == "cursor":
+        if event == "beforeShellExecution" or event == "afterShellExecution":
+            return [(gv_event, {**base, "tool_name": "Bash", "tool_input": {"command": payload.get("command", "")}})]
+        if event == "afterFileEdit":
+            edits = payload.get("edits") or []
+            return [
+                (
+                    gv_event,
+                    {
+                        **base,
+                        "tool_name": "Edit",
+                        "tool_input": {
+                            "file_path": payload.get("file_path", ""),
+                            "old_string": "\n".join(str(e.get("old_string", "")) for e in edits),
+                            "new_string": "\n".join(str(e.get("new_string", "")) for e in edits),
+                        },
+                    },
+                )
+            ]
+        if event == "beforeMCPExecution":
+            name = tool if tool.startswith("mcp__") else f"mcp__{payload.get('mcp_server_name', 'server')}__{tool}"
+            return [(gv_event, {**base, "tool_name": name, "tool_input": inp})]
+        # generic preToolUse: Cursor's own tool names
+        mapped = {
+            "Shell": "Bash",
+            "shell": "Bash",
+            "run_terminal_cmd": "Bash",
+            "edit_file": "Edit",
+            "write_file": "Write",
+            "Edit": "Edit",
+            "Write": "Write",
+        }.get(tool, tool)
+        if mapped == "Bash" and "command" not in inp and payload.get("command"):
+            inp["command"] = payload["command"]
+        return [(gv_event, {**base, "tool_name": mapped, "tool_input": inp})]
+    return [(gv_event, {**base, "tool_name": tool, "tool_input": inp})]
+
+
+def respond(agent: str, code: int, msg: str) -> tuple[int, str, str]:
+    """(exit code, stdout, stderr) in the agent's form. gitvow's code 2 means blocked; the message says DENY or CONFIRM."""
+    if agent == "cursor":
+        if code == 2:
+            perm = "deny" if msg.startswith("BLOCKED") else "ask"
+            return 0, json.dumps({"permission": perm, "user_message": msg, "agent_message": msg}), ""
+        return 0, json.dumps({"permission": "allow"}), msg
+    return code, "", msg

{gitvow-0.4.0 → gitvow-0.6.0}/src/gitvow/cli.py

@@ -9,6 +9,7 @@ import re
 import sys
 
 from . import __version__
+from . import snapshots as snap
 from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
 from .install import install_repo, install_user, uninstall_repo, uninstall_user
@@ -20,31 +21,56 @@ from .state import git
 
 
 def cmd_hook(a: argparse.Namespace) -> int:
+    from .adapters import normalize, respond
+
     try:
         payload = json.load(sys.stdin)
     except json.JSONDecodeError:
         payload = {}
-    handler = HANDLERS.get(a.event)
-    if not handler:
-        print(f"unknown hook event {a.event}", file=sys.stderr)
+    agent = a.agent or "claude"
+    try:
+        calls = normalize(agent, a.event, payload)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
         return 1
-    code, msg = handler(payload)
-    if msg:
-        print(msg, file=sys.stderr)
-    return code
+    if not calls:
+        return 0  # an event this adapter does not use
+    worst, messages = 0, []
+    for gv_event, p in calls:
+        handler = HANDLERS.get(gv_event)
+        if not handler:
+            print(f"unknown hook event {gv_event}", file=sys.stderr)
+            return 1
+        code, msg = handler(p)
+        if code == 2 and len(calls) > 1 and p.get("tool_input", {}).get("file_path"):
+            msg = f"{msg} [file: {p['tool_input']['file_path']}]"
+        worst = max(worst, code)
+        if msg:
+            messages.append(msg)
+    exit_code, out, err = respond(agent, worst, "\n".join(messages))
+    if out:
+        print(out)
+    if err:
+        print(err, file=sys.stderr)
+    return exit_code
 
 
 def cmd_install(a: argparse.Namespace) -> int:
-    done = install_user(os.path.expanduser("~")) if a.user else install_repo(os.path.abspath(a.repo))
+    agent = a.agent or "claude"
+    if a.user:
+        done = install_user(os.path.expanduser("~"), agent=agent)
+    else:
+        done = install_repo(os.path.abspath(a.repo), agent=agent)
     print("\n".join(done))
     return 0
 
 
 def cmd_uninstall(a: argparse.Namespace) -> int:
+    agent = a.agent or "claude"
     done = (
-        uninstall_user(os.path.expanduser("~"), a.purge_policy, a.purge_ledger)
+        uninstall_user(os.path.expanduser("~"), a.purge_policy, a.purge_ledger, agent=agent)
         if a.user
-        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes)
+        else uninstall_repo(os.path.abspath(a.repo), a.purge_notes, a.purge_snapshots, agent=agent)
     )
     print("\n".join(done))
     return 0
@@ -130,6 +156,61 @@ def cmd_report(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_snapshots(a: argparse.Namespace) -> int:
+    cwd = os.getcwd()
+    if a.sub == "prune":
+        days = None
+        if a.older_than:
+            m = re.fullmatch(r"(\d+)([dh]?)", a.older_than)
+            if not m:
+                print("--older-than takes a number of days, e.g. 14d", file=sys.stderr)
+                return 1
+            days = int(m.group(1)) / (24 if m.group(2) == "h" else 1)
+        print(f"pruned {snap.prune(cwd, days, a.session)} snapshot(s)")
+        return 0
+    rows = snap.list_snapshots(cwd, a.session)
+    if not rows:
+        print("no snapshots" + (f" for session {a.session}" if a.session else ""))
+        return 0
+    cur = None
+    for r in rows:
+        if r["session"] != cur:
+            cur = r["session"]
+            print(f"session {cur[:8]}   {sum(1 for x in rows if x['session'] == cur)} snapshots")
+            print("  n    taken                tool        file                                  changed vs HEAD")
+        print(
+            f"  {r['n']:<4d} {r['taken']:<20s} {r['tool']:<11s} {r['file'][:37]:<37s} {r['changed_files']} file{'s' if r['changed_files'] != 1 else ''}"
+        )
+    return 0
+
+
+def _resolve_or_fail(a: argparse.Namespace) -> str | None:
+    ref = snap.resolve(os.getcwd(), a.session, a.n)
+    if not ref:
+        print(f"no snapshot {a.n} for a unique session matching {a.session!r}", file=sys.stderr)
+    return ref
+
+
+def cmd_diff(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    print(snap.diff(os.getcwd(), ref, a.full))
+    return 0
+
+
+def cmd_restore(a: argparse.Namespace) -> int:
+    ref = _resolve_or_fail(a)
+    if not ref:
+        return 1
+    rc, msg = snap.restore(os.getcwd(), ref, a.to)
+    print(
+        f"restored {ref} into {msg} (detached worktree; remove with: git worktree remove {msg})" if rc == 0 else msg,
+        file=sys.stderr if rc else sys.stdout,
+    )
+    return rc
+
+
 def cmd_push_notes(a: argparse.Namespace) -> int:
     import subprocess
 
@@ -154,8 +235,10 @@ def cmd_summarize(a: argparse.Namespace) -> int:
 
 
 def cmd_selftest(a: argparse.Namespace) -> int:
-    from .selftest import run
+    from .selftest import run, run_agent
 
+    if a.agent and a.agent != "claude":
+        return run_agent(a.agent)
     return run()
 
 
@@ -163,12 +246,14 @@ def main(argv: list[str] | None = None) -> int:
     p = argparse.ArgumentParser(prog="gitvow", description="Provenance and policy gate for agent coding sessions.")
     p.add_argument("--version", action="version", version=f"gitvow {__version__}")
     sub = p.add_subparsers(dest="cmd", required=True)
-    s = sub.add_parser("hook", help="run as a Claude Code hook (reads JSON on stdin)")
+    s = sub.add_parser("hook", help="run as an agent hook (reads the agent's JSON on stdin)")
+    s.add_argument("--agent", choices=["claude", "codex", "gemini", "cursor"], default="claude")
     s.add_argument("event")
     s.set_defaults(f=cmd_hook)
     s = sub.add_parser("install", help="install per user (--user) or into a repo")
     s.add_argument("repo", nargs="?", default=".")
     s.add_argument("--user", action="store_true")
+    s.add_argument("--agent", choices=["claude", "codex", "gemini", "cursor"], default="claude")
     s.set_defaults(f=cmd_install)
     s = sub.add_parser("uninstall", help="remove what install added")
     s.add_argument("repo", nargs="?", default=".")
@@ -176,6 +261,8 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--purge-notes", action="store_true")
     s.add_argument("--purge-policy", action="store_true")
     s.add_argument("--purge-ledger", action="store_true")
+    s.add_argument("--purge-snapshots", action="store_true")
+    s.add_argument("--agent", choices=["claude", "codex", "gemini", "cursor"], default="claude")
     s.set_defaults(f=cmd_uninstall)
     s = sub.add_parser("check", help="dry-run the policy: gitvow check -- git push --force")
     s.add_argument("command", nargs="*")
@@ -199,6 +286,24 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--json", action="store_true")
     s.add_argument("--require-notes", action="store_true")
     s.set_defaults(f=cmd_report)
+    s = sub.add_parser(
+        "snapshots", help="list working-tree snapshots taken after agent edits; 'snapshots prune' deletes"
+    )
+    s.add_argument("sub", nargs="?", choices=["prune"])
+    s.add_argument("--session")
+    s.add_argument("--all", action="store_true")
+    s.add_argument("--older-than")
+    s.set_defaults(f=cmd_snapshots)
+    s = sub.add_parser("diff", help="what the agent had changed at snapshot n: gitvow diff <session> <n>")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--full", action="store_true")
+    s.set_defaults(f=cmd_diff)
+    s = sub.add_parser("restore", help="check a snapshot out into a detached scratch worktree")
+    s.add_argument("session")
+    s.add_argument("n", type=int)
+    s.add_argument("--to")
+    s.set_defaults(f=cmd_restore)
     s = sub.add_parser("push-notes", help="push refs/notes/gitvow/* to a remote (default origin)")
     s.add_argument("remote", nargs="?", default="origin")
     s.set_defaults(f=cmd_push_notes)
@@ -209,6 +314,7 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("dir")
     s.set_defaults(f=cmd_summarize)
     s = sub.add_parser("selftest", help="prove the hooks work here without touching a real repo")
+    s.add_argument("--agent", choices=["claude", "codex", "gemini", "cursor"], default="claude")
     s.set_defaults(f=cmd_selftest)
     a = p.parse_args(argv)
     return a.f(a)

{gitvow-0.4.0 → gitvow-0.6.0}/src/gitvow/hooks/__init__.py

@@ -8,6 +8,7 @@ import re
 import time
 from typing import Any
 
+from .. import snapshots
 from ..policy import PolicyError, evaluate, load_policy, message_for
 from ..redact import RedactionError, load_rules, redact
 from ..state import git, load_state, log_event, save_state, toplevel
@@ -15,7 +16,7 @@ from ..transcript import summarize
 
 NOTES_REF_PREFIX = "gitvow"  # refs/notes/gitvow/<session-id>; gitvow 0.1 wrote the single ref refs/notes/sessions
 LEGACY_NOTES_REF = "sessions"
-NOTE_SCHEMA = 2
+NOTE_SCHEMA = 3
 COMMIT_RE = re.compile(r"\bgit\s+commit\b")
 EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
 REDACTION_UNAVAILABLE = "redaction rules invalid; nothing written for this event"
@@ -37,6 +38,8 @@ def session_start(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
             "started": st.get("started") if same_session and st.get("started") else time.strftime("%Y-%m-%dT%H:%M:%S"),
             "steps": st.get("steps", 0) if same_session else 0,
             "agent_blobs": st.get("agent_blobs", {}) if same_session else {},
+            "snapshots": st.get("snapshots", 0) if same_session else 0,
+            "last_snapshot": st.get("last_snapshot") if same_session else None,
         }
     )
     st.pop("pending_commit", None)
@@ -160,8 +163,18 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
     tool = h.get("tool_name")
     inp = h.get("tool_input") or {}
     if tool in EDIT_TOOLS:
-        if inp.get("file_path"):
-            _record_agent_blob(cwd, str(inp["file_path"]))
+        fp = str(inp.get("file_path") or inp.get("notebook_path") or "")
+        if fp:
+            _record_agent_blob(cwd, fp)
+        try:
+            pol = load_policy(cwd, home)
+        except PolicyError:
+            pol = {}
+        cfg = snapshots.settings(pol)
+        if cfg.get("enabled", True):
+            ref = snapshots.take(cwd, h.get("session_id") or load_state(cwd).get("session_id"), tool, fp, cfg)
+            if ref:
+                log_event(cwd, "snapshot", {"ref": ref, "tool": tool})
         return 0, ""
     if tool != "Bash" or not COMMIT_RE.search(inp.get("command", "")):
         return 0, ""
@@ -194,6 +207,7 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
         "files_in_commit": [ln.strip() for ln in files.splitlines()[:-1]][:50] if files else [],
         "files_written_by_agent_this_session": [f["path"] for f in attribution["files"] if f["agent_wrote"]][:50],
         "attribution": attribution,
+        "snapshot": st.get("last_snapshot"),
         "transcript": "kept local; see ledger",
         "redaction": "secrets/PII patterns, high-entropy tokens and custom rules replaced at write time",
     }

{gitvow-0.4.0 → gitvow-0.6.0}/src/gitvow/install.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import shutil
 import sys
 from typing import Any
@@ -82,6 +83,120 @@ def _hook_entries(cmd_prefix: str) -> dict[str, list[dict[str, Any]]]:
     }
 
 
+AGENT_FILES = {
+    "claude": (".claude/settings.json", ".claude/settings.json"),
+    "codex": (".codex/hooks.json", ".codex/hooks.json"),
+    "gemini": (".gemini/settings.json", ".gemini/settings.json"),
+    "cursor": (".cursor/hooks.json", ".cursor/hooks.json"),
+}
+
+
+def _agent_entries(agent: str, cmd_prefix: str) -> dict[str, list[dict[str, Any]]]:
+    """Hook entries in each agent's own schema. Every command carries MARKER so install stays idempotent."""
+    c = f"{cmd_prefix} hook --agent {agent}"
+    if agent == "claude":
+        return _hook_entries(cmd_prefix)
+    if agent == "codex":
+
+        def e(ev: str, matcher: str | None) -> dict[str, Any]:
+            x: dict[str, Any] = {"hooks": [{"type": "command", "command": f"{c} {ev}", "timeout": 30}]}
+            if matcher:
+                x["matcher"] = matcher
+            return x
+
+        return {
+            "SessionStart": [e("SessionStart", None)],
+            "PreToolUse": [e("PreToolUse", "Bash|apply_patch|mcp__.*")],
+            "PostToolUse": [e("PostToolUse", "Bash|apply_patch")],
+            "Stop": [e("Stop", None)],
+        }
+    if agent == "gemini":
+
+        def g(ev: str, matcher: str) -> dict[str, Any]:
+            return {
+                "matcher": matcher,
+                "hooks": [{"name": f"gitvow-{ev}", "type": "command", "command": f"{c} {ev}", "timeout": 30000}],
+            }
+
+        return {
+            "SessionStart": [g("SessionStart", "*")],
+            "BeforeTool": [g("BeforeTool", "run_shell_command|write_file|replace|edit|mcp__.*")],
+            "AfterTool": [g("AfterTool", "run_shell_command|write_file|replace|edit")],
+            "SessionEnd": [g("SessionEnd", "*")],
+        }
+    if agent == "cursor":
+
+        def u(ev: str) -> dict[str, Any]:
+            return {"command": f"{c} {ev}", "type": "command", "timeout": 30, "failClosed": True}
+
+        return {
+            ev: [u(ev)]
+            for ev in (
+                "sessionStart",
+                "preToolUse",
+                "beforeShellExecution",
+                "beforeMCPExecution",
+                "afterFileEdit",
+                "afterShellExecution",
+                "stop",
+            )
+        }
+    raise ValueError(f"unknown agent {agent}")
+
+
+def _is_ours(entry: dict[str, Any]) -> bool:
+    if MARKER in (entry.get("command") or ""):
+        return True
+    return any(MARKER in (h.get("command") or "") for h in entry.get("hooks", []))
+
+
+def merge_agent_settings(path: str, agent: str, cmd_prefix: str) -> None:
+    cur: dict[str, Any] = {}
+    if os.path.exists(path):
+        with open(path) as fh:
+            cur = json.load(fh)
+    if agent == "cursor":
+        cur.setdefault("version", 1)
+    hooks = cur.setdefault("hooks", {})
+    for ev, entries in _agent_entries(agent, cmd_prefix).items():
+        kept = [x for x in hooks.get(ev, []) if not _is_ours(x)]
+        hooks[ev] = kept + entries
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "w") as fh:
+        json.dump(cur, fh, indent=2)
+
+
+def unmerge_agent_settings(path: str) -> None:
+    if not os.path.exists(path):
+        return
+    with open(path) as fh:
+        cur = json.load(fh)
+    hooks = cur.get("hooks", {})
+    for ev in list(hooks):
+        hooks[ev] = [x for x in hooks[ev] if not _is_ours(x)]
+        if not hooks[ev]:
+            del hooks[ev]
+    if not hooks:
+        cur.pop("hooks", None)
+    if cur and cur != {"version": 1}:
+        with open(path, "w") as fh:
+            json.dump(cur, fh, indent=2)
+    else:
+        os.remove(path)
+
+
+def codex_hooks_enabled_hint(home: str) -> str | None:
+    """Codex hooks are opt-in on some versions; point at the config line if it is absent."""
+    cfg = os.path.join(home, ".codex", "config.toml")
+    txt = ""
+    if os.path.exists(cfg):
+        with open(cfg) as fh:
+            txt = fh.read()
+    if re.search(r"^\s*hooks\s*=\s*true", txt, re.M) or re.search(r"^\s*codex_hooks\s*=\s*true", txt, re.M):
+        return None
+    return f"Codex hooks may need enabling: add `hooks = true` under [features] in {cfg}"
+
+
 def merge_settings(path: str, cmd_prefix: str) -> None:
     cur: dict[str, Any] = {}
     if os.path.exists(path):
@@ -125,7 +240,7 @@ def _write_git_hook(dirpath: str) -> str:
     return os.path.join(dirpath, "prepare-commit-msg")
 
 
-def install_user(home: str, cmd_prefix: str | None = None) -> list[str]:
+def install_user(home: str, cmd_prefix: str | None = None, agent: str = "claude") -> list[str]:
     base = os.path.join(home, ".gitvow")
     os.makedirs(base, exist_ok=True)
     cmd_prefix = cmd_prefix or executable_command()
@@ -137,21 +252,34 @@ def install_user(home: str, cmd_prefix: str | None = None) -> list[str]:
         shutil.copy(DEFAULT_POLICY_PATH, pol)
         done.append(f"default policy → {pol}")
     _write_git_hook(os.path.join(base, "git-hooks"))
-    merge_settings(os.path.join(home, ".claude", "settings.json"), cmd_prefix)
+    settings_rel = AGENT_FILES[agent][0]
+    if agent == "claude":
+        merge_settings(os.path.join(home, ".claude", "settings.json"), cmd_prefix)
+    else:
+        merge_agent_settings(os.path.join(home, settings_rel), agent, cmd_prefix)
+        if agent == "codex":
+            hint = codex_hooks_enabled_hint(home)
+            if hint:
+                done.append(hint)
     git(["config", "--global", "core.hooksPath", os.path.join(base, "git-hooks")], home)
     _set_notes_config(home, ["--global"])
     done += [
-        "hooks merged into ~/.claude/settings.json",
+        f"hooks merged into ~/{settings_rel}",
         "global core.hooksPath → ~/.gitvow/git-hooks",
         f"global notes.displayRef / notes.rewriteRef → {NOTES_GLOB}",
     ]
     return done
 
 
-def uninstall_user(home: str, purge_policy: bool = False, purge_ledger: bool = False) -> list[str]:
+def uninstall_user(
+    home: str, purge_policy: bool = False, purge_ledger: bool = False, agent: str = "claude"
+) -> list[str]:
     base = os.path.join(home, ".gitvow")
     done = []
-    unmerge_settings(os.path.join(home, ".claude", "settings.json"))
+    if agent == "claude":
+        unmerge_settings(os.path.join(home, ".claude", "settings.json"))
+    else:
+        unmerge_agent_settings(os.path.join(home, AGENT_FILES[agent][0]))
     rc, cur, _ = git(["config", "--global", "--get", "core.hooksPath"], home)
     if rc == 0 and cur == os.path.join(base, "git-hooks"):
         git(["config", "--global", "--unset", "core.hooksPath"], home)
@@ -164,11 +292,11 @@ def uninstall_user(home: str, purge_policy: bool = False, purge_ledger: bool = F
     if purge_ledger:
         shutil.rmtree(os.path.join(base, "ledger"), ignore_errors=True)
         done.append("ledger removed")
-    done.append("hook entries removed from ~/.claude/settings.json")
+    done.append(f"hook entries removed from ~/{AGENT_FILES[agent][0]}")
     return done
 
 
-def install_repo(repo: str, cmd_prefix: str = "gitvow") -> list[str]:
+def install_repo(repo: str, cmd_prefix: str = "gitvow", agent: str = "claude") -> list[str]:
     base = os.path.join(repo, ".gitvow")
     os.makedirs(base, exist_ok=True)
     from .policy import DEFAULT_POLICY_PATH
@@ -177,21 +305,29 @@ def install_repo(repo: str, cmd_prefix: str = "gitvow") -> list[str]:
     if not os.path.exists(pol):
         shutil.copy(DEFAULT_POLICY_PATH, pol)
     _write_git_hook(os.path.join(base, "git-hooks"))
-    merge_settings(os.path.join(repo, ".claude", "settings.json"), cmd_prefix)
+    if agent == "claude":
+        merge_settings(os.path.join(repo, ".claude", "settings.json"), cmd_prefix)
+    else:
+        merge_agent_settings(os.path.join(repo, AGENT_FILES[agent][1]), agent, cmd_prefix)
     git(["config", "core.hooksPath", ".gitvow/git-hooks"], repo)
     _set_notes_config(repo, [])
     return [
         f"policy → {pol}",
-        "hooks merged into .claude/settings.json",
+        f"hooks merged into {AGENT_FILES[agent][1]}",
         "core.hooksPath → .gitvow/git-hooks",
         f"notes.displayRef / notes.rewriteRef → {NOTES_GLOB}",
         "commit .gitvow/ and .claude/settings.json to share; teammates run: git config core.hooksPath .gitvow/git-hooks",
     ]
 
 
-def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
+def uninstall_repo(
+    repo: str, purge_notes: bool = False, purge_snapshots: bool = False, agent: str = "claude"
+) -> list[str]:
     done = []
-    unmerge_settings(os.path.join(repo, ".claude", "settings.json"))
+    if agent == "claude":
+        unmerge_settings(os.path.join(repo, ".claude", "settings.json"))
+    else:
+        unmerge_agent_settings(os.path.join(repo, AGENT_FILES[agent][1]))
     rc, cur, _ = git(["config", "--get", "core.hooksPath"], repo)
     if rc == 0 and cur == ".gitvow/git-hooks":
         git(["config", "--unset", "core.hooksPath"], repo)
@@ -210,5 +346,9 @@ def uninstall_repo(repo: str, purge_notes: bool = False) -> list[str]:
         for ref in refs.split():
             git(["update-ref", "-d", ref], repo)
         done.append(f"{len(refs.split())} local session note ref(s) deleted (remote copies untouched)")
+    if purge_snapshots:
+        from . import snapshots as _snap
+
+        done.append(f"{_snap.purge_all(repo)} snapshot ref(s) deleted")
     done.append(".gitvow removed; commit trailers already in history remain")
     return done