tripwire-git 0.1.0__tar.gz → 0.2.0__tar.gz

{tripwire_git-0.1.0/src/tripwire_git.egg-info → tripwire_git-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tripwire-git
-Version: 0.1.0
+Version: 0.2.0
 Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
 License: MIT
 Keywords: git,code-owners,approval,pre-receive,ci
@@ -96,6 +96,38 @@ server-side or CI check below remains the real gate. Nothing can stop someone
 from editing files in their own clone; tripwire stops unapproved changes from
 landing on protected branches.
 
+## AI coding agents (Claude Code)
+
+Stop an AI agent from changing protected code *before* it touches the disk:
+
+```bash
+tripwire install-claude-hook      # adds a PreToolUse hook to .claude/settings.json
+```
+
+The agent acts as its own identity (`TRIPWIRE_AI_ACTOR`, default `ai-agent`),
+which is not an owner unless you list it. When it tries to `Edit`, `MultiEdit`
+or `Write` a protected block, the call is refused with a message naming who may
+approve it, and the request is recorded. A human then approves that exact
+change **from an interactive terminal**:
+
+```bash
+tripwire pending                                  # what was blocked
+tripwire grant <id> --approver anna               # the agent can now retry the same edit
+```
+
+The approval is bound to the exact before/after content, so a different edit
+is blocked again. To let the agent edit a block freely, list its identity as an
+owner of that lock. Rules are read from the committed version (`HEAD`), and the
+agent cannot edit the rules or approvals files, run `tripwire grant`, or touch
+those files through `Bash`.
+
+Limits: shell commands that rewrite files (`sed -i`, redirects, scripts) are not
+inspected, so keep the pre-commit hook and the server / CI check as backstops.
+`grant` trusts whoever runs it in a terminal; a person with shell access can
+also edit `.tripwire/approvals.json` by hand. Verified with simulated hook
+payloads in the documented format, not yet end to end inside a live Claude Code
+session.
+
 ## Platforms
 
 | Platform | Enforce with | Approvals from | Verified |

tripwire_git-0.1.0/PKG-INFO → tripwire_git-0.2.0/README.md

@@ -1,155 +1,168 @@
-Metadata-Version: 2.4
-Name: tripwire-git
-Version: 0.1.0
-Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
-License: MIT
-Keywords: git,code-owners,approval,pre-receive,ci
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Version Control :: Git
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Dynamic: license-file
-
-# tripwire
-
-Protect blocks of code in Git. A protected block can only be changed by its
-owner or a leader, or by someone whose change an authorized person approved.
-Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
-required check on GitHub, GitLab and Gitea / Forgejo.
-
-## Quick start
-
-1. Mark a block in any language, inside a comment:
-
-   ```python
-   # @lock-begin billing
-   RATE = 5
-   # @lock-end billing
-   ```
-
-2. Create `.tripwire/locks.json` (see `locks.example.json`):
-
-   ```json
-   {
-     "leaders": ["alice"],
-     "locks": [
-       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
-       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
-     ]
-   }
-   ```
-
-3. Check a change:
-
-   ```bash
-   pip install tripwire-git
-   tripwire preflight --actor dave        # uncommitted changes vs HEAD
-   ```
-
-   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
-   alice, bob, carol`, exit code 1.
-
-## Concepts
-
-- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
-  folders are locked with path patterns (`dir/` prefix or glob).
-- Owners and leaders may edit freely. Anyone else needs an approval from an
-  owner, an approver or a leader. You cannot approve your own change.
-- Approvals are bound to the exact before/after content of the protected
-  block (a SHA-256 digest). Edit the code again and the approval is void.
-- Rules are always read from the **base** revision (the target branch), so a
-  change cannot rewrite the rules that judge it. Changing the rules file is
-  leaders-only and cannot be approved.
-- Whitespace-only edits are ignored. Deleting markers counts as a change.
-  Unclosed blocks extend to end of file. A marker whose id is missing from the
-  rules is leaders-only.
-
-## Commands
-
-```bash
-tripwire preflight --actor alice                              # uncommitted changes vs HEAD
-tripwire check --base origin/main --head HEAD --actor alice   # a commit range
-tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
-tripwire preflight --staged                                   # staged changes only
-tripwire install-hook                                         # local pre-commit hook
-tripwire pre-receive                                          # server hook, reads stdin
-tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
-```
-
-Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
-
-## Local early warning
-
-`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
-and refuses the commit when a protected block is touched without permission
-(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
-identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
-`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
-server-side or CI check below remains the real gate. Nothing can stop someone
-from editing files in their own clone; tripwire stops unapproved changes from
-landing on protected branches.
-
-## Platforms
-
-| Platform | Enforce with | Approvals from | Verified |
-|---|---|---|---|
-| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
-| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
-| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
-| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
-
-On hosted services, also forbid direct pushes to the protected branch and add a
-path lock for the CI configuration, otherwise a PR can delete the check.
-
-**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
-`TRIPWIRE_ACTOR` from your server's authenticated user.
-
-**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
-the PR's current head commit, so a new push voids it. Reviewer logins are
-matched to names in `locks.json` case-insensitively; teams are not supported.
-
-**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
-approvals endpoint is not bound to a commit, so enable "Remove all approvals
-when commits are added to the source branch"; tripwire cannot verify it.
-
-**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
-reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
-`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
-
-## Architecture
-
-- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
-- `review.py`: shared pull / merge request check used by the platform adapters
-- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
-- `approvals.py`: local approvals file
-- `gitio.py`, `cli.py`: Git access and command line
-
-## Limits
-
-- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
-  trustworthy as whatever sets it. On hosted platforms it is the PR author.
-- The local approvals file is trust-based: anyone able to commit could write an
-  entry naming an approver. Use platform approvals for real deployments.
-- On every platform, people who can edit branch protection or CI settings are
-  trusted; tripwire cannot stop an admin from switching the rule off.
-- Pushes with several authors are checked as one cumulative diff by the pusher.
-- Whitespace-insensitive comparison also ignores indentation changes.
-- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
-
-## Development
-
-```bash
-pip install -e .[dev]
-pytest
-```
-
-## License
-
-MIT
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## AI coding agents (Claude Code)
+
+Stop an AI agent from changing protected code *before* it touches the disk:
+
+```bash
+tripwire install-claude-hook      # adds a PreToolUse hook to .claude/settings.json
+```
+
+The agent acts as its own identity (`TRIPWIRE_AI_ACTOR`, default `ai-agent`),
+which is not an owner unless you list it. When it tries to `Edit`, `MultiEdit`
+or `Write` a protected block, the call is refused with a message naming who may
+approve it, and the request is recorded. A human then approves that exact
+change **from an interactive terminal**:
+
+```bash
+tripwire pending                                  # what was blocked
+tripwire grant <id> --approver anna               # the agent can now retry the same edit
+```
+
+The approval is bound to the exact before/after content, so a different edit
+is blocked again. To let the agent edit a block freely, list its identity as an
+owner of that lock. Rules are read from the committed version (`HEAD`), and the
+agent cannot edit the rules or approvals files, run `tripwire grant`, or touch
+those files through `Bash`.
+
+Limits: shell commands that rewrite files (`sed -i`, redirects, scripts) are not
+inspected, so keep the pre-commit hook and the server / CI check as backstops.
+`grant` trusts whoever runs it in a terminal; a person with shell access can
+also edit `.tripwire/approvals.json` by hand. Verified with simulated hook
+payloads in the documented format, not yet end to end inside a live Claude Code
+session.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; teams are not supported.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- Whitespace-insensitive comparison also ignores indentation changes.
+- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

{tripwire_git-0.1.0 → tripwire_git-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tripwire-git"
-version = "0.1.0"
+version = "0.2.0"
 description = "Protect blocks of code in Git: changes need approval from an owner, an approver or a leader."
 readme = "README.md"
 requires-python = ">=3.9"

{tripwire_git-0.1.0 → tripwire_git-0.2.0}/src/tripwire/__init__.py

@@ -1,3 +1,3 @@
 """tripwire: approval-gated protection for blocks of code in Git."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

tripwire_git-0.2.0/src/tripwire/aiguard.py

@@ -0,0 +1,135 @@
+"""Guard for AI coding agents (Claude Code PreToolUse hook).
+
+The agent acts as its own identity (TRIPWIRE_AI_ACTOR, default "ai-agent"). An
+edit to a protected block is refused before it reaches the disk; the refusal is
+recorded as a pending request. A human approves it from a real terminal with
+`tripwire grant`, after which the agent can retry the exact same edit.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import List, Optional
+
+from .approvals import parse_local
+from .config import APPROVALS_PATH, RULES_PATH, parse_config
+from .engine import evaluate
+from .gitio import RevSource, WorktreeSource, git
+from .models import Decision, FileChange, Violation
+
+DEFAULT_AI_ACTOR = "ai-agent"
+# Best-effort: stop the agent from approving itself or rewriting the rules via the shell.
+GUARDED_BASH = (
+    "tripwire grant",
+    ".tripwire/approvals.json",
+    ".tripwire\\approvals.json",
+    ".tripwire/locks.json",
+    ".tripwire\\locks.json",
+)
+
+
+def ai_actor() -> str:
+    return os.environ.get("TRIPWIRE_AI_ACTOR") or DEFAULT_AI_ACTOR
+
+
+def _apply_edit(content: str, old: str, new: str, replace_all: bool) -> Optional[str]:
+    if old not in content:
+        return None  # the tool itself will fail; nothing to guard
+    if replace_all:
+        return content.replace(old, new)
+    if content.count(old) != 1:
+        return None
+    return content.replace(old, new, 1)
+
+
+def proposed_changes(root: str, tool: str, tool_input: dict, cwd: str) -> List[FileChange]:
+    path = tool_input.get("file_path")
+    if not path:
+        return []
+    full = path if os.path.isabs(path) else os.path.join(cwd, path)
+    try:
+        rel = os.path.relpath(full, root).replace(os.sep, "/")
+    except ValueError:  # different drive
+        return []
+    if rel.startswith(".."):
+        return []
+    old = WorktreeSource(root).read(rel)
+    if tool == "Write":
+        return [FileChange(rel, old, tool_input.get("content", ""))]
+    if old is None:
+        return []
+    if tool == "Edit":
+        edits = [tool_input]
+    elif tool == "MultiEdit":
+        edits = tool_input.get("edits") or []
+    else:
+        return []
+    new = old.replace("\r\n", "\n")  # match regardless of the file's line endings
+    for e in edits:
+        new = _apply_edit(
+            new,
+            e.get("old_string", "").replace("\r\n", "\n"),
+            e.get("new_string", "").replace("\r\n", "\n"),
+            bool(e.get("replace_all")),
+        )
+        if new is None:
+            return []
+    return [FileChange(rel, old, new)]
+
+
+def pending_path(root: str) -> str:
+    git_dir = git(root, "rev-parse", "--absolute-git-dir").decode().strip()
+    return os.path.join(git_dir, "tripwire", "pending.json")
+
+
+def load_pending(root: str) -> List[dict]:
+    path = pending_path(root)
+    if not os.path.isfile(path):
+        return []
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def save_pending(root: str, items: List[dict]) -> None:
+    path = pending_path(root)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(items, fh, indent=2)
+
+
+def _record_pending(root: str, decision: Decision) -> None:
+    items = load_pending(root)
+    known = {i["digest"] for i in items}
+    for v in decision.violations:
+        if v.digest and v.digest not in known:
+            items.append({"digest": v.digest, "lock": v.lock_id, "path": v.path, "message": v.message, "time": int(time.time())})
+    save_pending(root, items)
+
+
+def check_tool_call(root: str, payload: dict) -> Decision:
+    tool = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input") or {}
+
+    if tool == "Bash":
+        command = tool_input.get("command", "")
+        if any(token in command for token in GUARDED_BASH):
+            return Decision([Violation("<bash>", "", "shell commands may not touch tripwire approvals or rules")])
+        return Decision()
+
+    changes = proposed_changes(root, tool, tool_input, payload.get("cwd") or root)
+    if not changes:
+        return Decision()
+    if changes[0].path == APPROVALS_PATH:
+        return Decision([Violation("<approvals>", APPROVALS_PATH, "the agent may not edit the approvals file; a human uses `tripwire grant`")])
+
+    rules = RevSource(root, "HEAD").read(RULES_PATH)  # rules always come from the committed version
+    if rules is None:
+        return Decision()
+    config = parse_config(rules)
+    approvals = parse_local(WorktreeSource(root).read(APPROVALS_PATH))
+    decision = evaluate(config, changes, ai_actor(), approvals)
+    if not decision.allowed:
+        _record_pending(root, decision)
+    return decision

{tripwire_git-0.1.0 → tripwire_git-0.2.0}/src/tripwire/cli.py

@@ -157,6 +157,85 @@ def cmd_gitlab_check(args, root: str) -> int:
     return report(check_merge_request(root, GitLabClient.from_env(args.gitlab_project), int(iid)))
 
 
+def cmd_claude_hook(args, root: str) -> int:
+    from .aiguard import check_tool_call
+
+    decision = check_tool_call(root, json.load(sys.stdin))
+    if decision.allowed:
+        return 0
+    print("tripwire: blocked for the AI agent", file=sys.stderr)
+    for v in decision.violations:
+        print("  - " + v.message, file=sys.stderr)
+    if any(v.digest for v in decision.violations):
+        print("A human can approve this exact change with `tripwire pending` and `tripwire grant <id> --approver <name>`; then retry the same edit.", file=sys.stderr)
+    return 2  # exit code 2 makes Claude Code refuse the tool call and show stderr to the agent
+
+
+def cmd_pending(args, root: str) -> int:
+    from .aiguard import load_pending
+
+    items = load_pending(root)
+    for i in items:
+        print("%s  %s  %s" % (i["digest"][:12], i["lock"], i["message"]))
+    if not items:
+        print("tripwire: no pending requests")
+    return 0
+
+
+def cmd_grant(args, root: str) -> int:
+    from .aiguard import load_pending, save_pending
+
+    if not sys.stdin.isatty() and not os.environ.get("TRIPWIRE_ALLOW_NONINTERACTIVE"):
+        print("tripwire: grant must be run by a human in an interactive terminal", file=sys.stderr)
+        return 1
+    items = load_pending(root)
+    matches = [i for i in items if i["digest"].startswith(args.digest)]
+    if len(matches) != 1:
+        print("tripwire: %d pending requests match %r" % (len(matches), args.digest), file=sys.stderr)
+        return 1
+    item = matches[0]
+    rules = RevSource(root, "HEAD").read(RULES_PATH)
+    if rules is None:
+        print("tripwire: no rules file at HEAD", file=sys.stderr)
+        return 2
+    config = parse_config(rules)
+    lock = config.get(item["lock"])
+    allowed = set(config.leaders) | (set(lock.owners) | set(lock.approvers) if lock else set())
+    if args.approver not in allowed:
+        print("tripwire: %s may not approve %s" % (args.approver, item["lock"]), file=sys.stderr)
+        return 1
+    path = os.path.join(root, APPROVALS_PATH)
+    existing: List[Approval] = []
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as fh:
+            existing = parse_local(fh.read())
+    existing.append(Approval(item["lock"], args.approver, item["digest"]))
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(dump_local(existing))
+    save_pending(root, [i for i in items if i is not item])
+    print("tripwire: approved %s as %s" % (item["digest"][:12], args.approver))
+    return 0
+
+
+def cmd_install_claude_hook(args, root: str) -> int:
+    path = os.path.join(root, ".claude", "settings.json")
+    settings = {}
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as fh:
+            settings = json.load(fh)
+    entry = {"type": "command", "command": args.command}
+    groups = settings.setdefault("hooks", {}).setdefault("PreToolUse", [])
+    if not any(entry in g.get("hooks", []) for g in groups):
+        groups.append({"matcher": "Edit|Write|MultiEdit|Bash", "hooks": [entry]})
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(settings, fh, indent=2)
+        fh.write("\n")
+    print("tripwire: Claude Code hook installed in %s" % path)
+    return 0
+
+
 def cmd_approve(args, root: str) -> int:
     config, decision = run_check(root, args.base, args.head, actor="")
     if config is None:
@@ -225,6 +304,17 @@ def build_parser() -> argparse.ArgumentParser:
     gl.add_argument("--gitlab-project", help="project id or path (default: CI_PROJECT_ID)")
     gl.set_defaults(func=cmd_gitlab_check)
 
+    sub.add_parser("claude-hook", help="Claude Code PreToolUse hook: reads the tool call from stdin").set_defaults(func=cmd_claude_hook)
+    ih = sub.add_parser("install-claude-hook", help="add the hook to .claude/settings.json")
+    ih.add_argument("--command", default="tripwire claude-hook", help="hook command (default: tripwire claude-hook)")
+    ih.set_defaults(func=cmd_install_claude_hook)
+    sub.add_parser("pending", help="list edits the AI agent was blocked from making").set_defaults(func=cmd_pending)
+
+    gr = sub.add_parser("grant", help="a human approves a pending AI edit (interactive terminal only)")
+    gr.add_argument("digest", help="id (prefix) from `tripwire pending`")
+    gr.add_argument("--approver", required=True)
+    gr.set_defaults(func=cmd_grant)
+
     a = sub.add_parser("approve", help="record an approval for the pending change")
     a.add_argument("--base", required=True)
     a.add_argument("--head")
@@ -237,7 +327,13 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: Optional[List[str]] = None) -> int:
     args = build_parser().parse_args(argv)
     try:
-        root = toplevel(args.repo) if args.command != "pre-receive" else os.path.abspath(args.repo)
+        if args.command == "claude-hook":
+            try:
+                root = toplevel(args.repo)
+            except GitError:
+                return 0  # not a git repository: nothing to guard
+        else:
+            root = toplevel(args.repo) if args.command != "pre-receive" else os.path.abspath(args.repo)
         return args.func(args, root)
     except (ConfigError, GitError) as exc:
         print("tripwire: error: %s" % exc, file=sys.stderr)

tripwire_git-0.1.0/README.md → tripwire_git-0.2.0/src/tripwire_git.egg-info/PKG-INFO

@@ -1,136 +1,187 @@
-# tripwire
-
-Protect blocks of code in Git. A protected block can only be changed by its
-owner or a leader, or by someone whose change an authorized person approved.
-Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
-required check on GitHub, GitLab and Gitea / Forgejo.
-
-## Quick start
-
-1. Mark a block in any language, inside a comment:
-
-   ```python
-   # @lock-begin billing
-   RATE = 5
-   # @lock-end billing
-   ```
-
-2. Create `.tripwire/locks.json` (see `locks.example.json`):
-
-   ```json
-   {
-     "leaders": ["alice"],
-     "locks": [
-       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
-       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
-     ]
-   }
-   ```
-
-3. Check a change:
-
-   ```bash
-   pip install tripwire-git
-   tripwire preflight --actor dave        # uncommitted changes vs HEAD
-   ```
-
-   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
-   alice, bob, carol`, exit code 1.
-
-## Concepts
-
-- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
-  folders are locked with path patterns (`dir/` prefix or glob).
-- Owners and leaders may edit freely. Anyone else needs an approval from an
-  owner, an approver or a leader. You cannot approve your own change.
-- Approvals are bound to the exact before/after content of the protected
-  block (a SHA-256 digest). Edit the code again and the approval is void.
-- Rules are always read from the **base** revision (the target branch), so a
-  change cannot rewrite the rules that judge it. Changing the rules file is
-  leaders-only and cannot be approved.
-- Whitespace-only edits are ignored. Deleting markers counts as a change.
-  Unclosed blocks extend to end of file. A marker whose id is missing from the
-  rules is leaders-only.
-
-## Commands
-
-```bash
-tripwire preflight --actor alice                              # uncommitted changes vs HEAD
-tripwire check --base origin/main --head HEAD --actor alice   # a commit range
-tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
-tripwire preflight --staged                                   # staged changes only
-tripwire install-hook                                         # local pre-commit hook
-tripwire pre-receive                                          # server hook, reads stdin
-tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
-```
-
-Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
-
-## Local early warning
-
-`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
-and refuses the commit when a protected block is touched without permission
-(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
-identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
-`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
-server-side or CI check below remains the real gate. Nothing can stop someone
-from editing files in their own clone; tripwire stops unapproved changes from
-landing on protected branches.
-
-## Platforms
-
-| Platform | Enforce with | Approvals from | Verified |
-|---|---|---|---|
-| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
-| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
-| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
-| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
-
-On hosted services, also forbid direct pushes to the protected branch and add a
-path lock for the CI configuration, otherwise a PR can delete the check.
-
-**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
-`TRIPWIRE_ACTOR` from your server's authenticated user.
-
-**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
-the PR's current head commit, so a new push voids it. Reviewer logins are
-matched to names in `locks.json` case-insensitively; teams are not supported.
-
-**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
-approvals endpoint is not bound to a commit, so enable "Remove all approvals
-when commits are added to the source branch"; tripwire cannot verify it.
-
-**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
-reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
-`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
-
-## Architecture
-
-- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
-- `review.py`: shared pull / merge request check used by the platform adapters
-- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
-- `approvals.py`: local approvals file
-- `gitio.py`, `cli.py`: Git access and command line
-
-## Limits
-
-- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
-  trustworthy as whatever sets it. On hosted platforms it is the PR author.
-- The local approvals file is trust-based: anyone able to commit could write an
-  entry naming an approver. Use platform approvals for real deployments.
-- On every platform, people who can edit branch protection or CI settings are
-  trusted; tripwire cannot stop an admin from switching the rule off.
-- Pushes with several authors are checked as one cumulative diff by the pusher.
-- Whitespace-insensitive comparison also ignores indentation changes.
-- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
-
-## Development
-
-```bash
-pip install -e .[dev]
-pytest
-```
-
-## License
-
-MIT
+Metadata-Version: 2.4
+Name: tripwire-git
+Version: 0.2.0
+Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
+License: MIT
+Keywords: git,code-owners,approval,pre-receive,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## AI coding agents (Claude Code)
+
+Stop an AI agent from changing protected code *before* it touches the disk:
+
+```bash
+tripwire install-claude-hook      # adds a PreToolUse hook to .claude/settings.json
+```
+
+The agent acts as its own identity (`TRIPWIRE_AI_ACTOR`, default `ai-agent`),
+which is not an owner unless you list it. When it tries to `Edit`, `MultiEdit`
+or `Write` a protected block, the call is refused with a message naming who may
+approve it, and the request is recorded. A human then approves that exact
+change **from an interactive terminal**:
+
+```bash
+tripwire pending                                  # what was blocked
+tripwire grant <id> --approver anna               # the agent can now retry the same edit
+```
+
+The approval is bound to the exact before/after content, so a different edit
+is blocked again. To let the agent edit a block freely, list its identity as an
+owner of that lock. Rules are read from the committed version (`HEAD`), and the
+agent cannot edit the rules or approvals files, run `tripwire grant`, or touch
+those files through `Bash`.
+
+Limits: shell commands that rewrite files (`sed -i`, redirects, scripts) are not
+inspected, so keep the pre-commit hook and the server / CI check as backstops.
+`grant` trusts whoever runs it in a terminal; a person with shell access can
+also edit `.tripwire/approvals.json` by hand. Verified with simulated hook
+payloads in the documented format, not yet end to end inside a live Claude Code
+session.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; teams are not supported.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- Whitespace-insensitive comparison also ignores indentation changes.
+- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

{tripwire_git-0.1.0 → tripwire_git-0.2.0}/src/tripwire_git.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 src/tripwire/__init__.py
 src/tripwire/__main__.py
+src/tripwire/aiguard.py
 src/tripwire/approvals.py
 src/tripwire/blocks.py
 src/tripwire/cli.py
@@ -21,6 +22,7 @@ src/tripwire_git.egg-info/dependency_links.txt
 src/tripwire_git.egg-info/entry_points.txt
 src/tripwire_git.egg-info/requires.txt
 src/tripwire_git.egg-info/top_level.txt
+tests/test_aiguard.py
 tests/test_engine.py
 tests/test_git.py
 tests/test_gitea.py

tripwire_git-0.2.0/tests/test_aiguard.py

@@ -0,0 +1,136 @@
+import io
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+from tripwire.cli import main
+
+RULES = {
+    "leaders": ["lead"],
+    "locks": [{"id": "billing", "owners": ["olga"], "approvers": ["anna"]}],
+}
+CODE = "x = 1\n# @lock-begin billing\nrate = 5\n# @lock-end billing\ny = 2\n"
+
+
+def git(cwd, *args):
+    env = {**os.environ, "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t", "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t"}
+    return subprocess.run(["git", *args], cwd=cwd, env=env, capture_output=True, text=True, check=True).stdout.strip()
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    git(tmp_path, "init", "-q", "-b", "main")
+    (tmp_path / ".tripwire").mkdir()
+    (tmp_path / ".tripwire" / "locks.json").write_text(json.dumps(RULES))
+    (tmp_path / "app.py").write_text(CODE)
+    git(tmp_path, "add", "-A")
+    git(tmp_path, "commit", "-q", "-m", "init")
+    monkeypatch.delenv("TRIPWIRE_AI_ACTOR", raising=False)
+    monkeypatch.setenv("TRIPWIRE_ALLOW_NONINTERACTIVE", "1")
+    return tmp_path
+
+
+def hook(repo, monkeypatch, tool, tool_input):
+    payload = {"tool_name": tool, "tool_input": tool_input, "cwd": str(repo)}
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+    return main(["--repo", str(repo), "claude-hook"])
+
+
+def edit(repo, old, new, **kw):
+    return {"file_path": str(repo / "app.py"), "old_string": old, "new_string": new, **kw}
+
+
+def test_edit_of_protected_block_is_blocked_before_it_happens(repo, monkeypatch, capsys):
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "rate = 5", "rate = 9")) == 2
+    err = capsys.readouterr().err
+    assert "billing" in err and "tripwire grant" in err
+    assert (repo / "app.py").read_text() == CODE  # hook never touches the file
+
+
+def test_edit_of_unprotected_code_is_allowed(repo, monkeypatch):
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "y = 2", "y = 3")) == 0
+
+
+def test_write_that_changes_protected_block_is_blocked(repo, monkeypatch):
+    new = CODE.replace("rate = 5", "rate = 9")
+    assert hook(repo, monkeypatch, "Write", {"file_path": str(repo / "app.py"), "content": new}) == 2
+
+
+def test_write_that_leaves_block_unchanged_is_allowed(repo, monkeypatch):
+    new = CODE.replace("y = 2", "y = 7")
+    assert hook(repo, monkeypatch, "Write", {"file_path": str(repo / "app.py"), "content": new}) == 0
+
+
+def test_multiedit_is_evaluated_as_a_whole(repo, monkeypatch):
+    edits = [{"old_string": "y = 2", "new_string": "y = 3"}, {"old_string": "rate = 5", "new_string": "rate = 6"}]
+    assert hook(repo, monkeypatch, "MultiEdit", {"file_path": str(repo / "app.py"), "edits": edits}) == 2
+
+
+def test_deleting_markers_is_blocked(repo, monkeypatch):
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "# @lock-begin billing\n", "")) == 2
+
+
+def test_failing_edit_is_left_to_the_tool(repo, monkeypatch):
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "no such text", "z")) == 0
+
+
+def test_ai_actor_can_be_made_owner(repo, monkeypatch):
+    monkeypatch.setenv("TRIPWIRE_AI_ACTOR", "olga")
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "rate = 5", "rate = 9")) == 0
+
+
+def test_path_outside_repo_and_other_tools_are_ignored(repo, monkeypatch, tmp_path_factory):
+    other = tmp_path_factory.mktemp("elsewhere") / "f.py"
+    assert hook(repo, monkeypatch, "Write", {"file_path": str(other), "content": "x"}) == 0
+    assert hook(repo, monkeypatch, "Read", {"file_path": str(repo / "app.py")}) == 0
+
+
+def test_bash_cannot_touch_approvals_or_grant(repo, monkeypatch):
+    assert hook(repo, monkeypatch, "Bash", {"command": "tripwire grant abc --approver anna"}) == 2
+    assert hook(repo, monkeypatch, "Bash", {"command": "echo [] > .tripwire/approvals.json"}) == 2
+    assert hook(repo, monkeypatch, "Bash", {"command": "ls"}) == 0
+
+
+def test_agent_cannot_edit_approvals_or_rules_files(repo, monkeypatch):
+    f = {"file_path": str(repo / ".tripwire" / "approvals.json"), "content": "[]"}
+    assert hook(repo, monkeypatch, "Write", f) == 2
+    r = {"file_path": str(repo / ".tripwire" / "locks.json"), "content": json.dumps(dict(RULES, leaders=["ai-agent"]))}
+    assert hook(repo, monkeypatch, "Write", r) == 2
+
+
+def test_grant_then_same_edit_is_allowed_but_other_edit_is_not(repo, monkeypatch, capsys):
+    e = edit(repo, "rate = 5", "rate = 9")
+    assert hook(repo, monkeypatch, "Edit", e) == 2
+    assert main(["--repo", str(repo), "pending"]) == 0
+    digest = json.loads((repo / ".git" / "tripwire" / "pending.json").read_text())[0]["digest"]
+    assert main(["--repo", str(repo), "grant", digest[:10], "--approver", "bob"]) == 1  # not an approver
+    assert main(["--repo", str(repo), "grant", digest[:10], "--approver", "anna"]) == 0
+    assert hook(repo, monkeypatch, "Edit", e) == 0
+    assert hook(repo, monkeypatch, "Edit", edit(repo, "rate = 5", "rate = 10")) == 2  # approval was for rate = 9
+
+
+def test_grant_refuses_non_interactive_use(repo, monkeypatch):
+    hook(repo, monkeypatch, "Edit", edit(repo, "rate = 5", "rate = 9"))
+    digest = json.loads((repo / ".git" / "tripwire" / "pending.json").read_text())[0]["digest"]
+    monkeypatch.delenv("TRIPWIRE_ALLOW_NONINTERACTIVE")
+    monkeypatch.setattr(sys, "stdin", io.StringIO(""))
+    assert main(["--repo", str(repo), "grant", digest[:10], "--approver", "anna"]) == 1
+    assert not (repo / ".tripwire" / "approvals.json").exists()
+
+
+def test_install_claude_hook_is_idempotent_and_keeps_other_settings(repo):
+    (repo / ".claude").mkdir()
+    (repo / ".claude" / "settings.json").write_text(json.dumps({"model": "x"}))
+    assert main(["--repo", str(repo), "install-claude-hook"]) == 0
+    assert main(["--repo", str(repo), "install-claude-hook"]) == 0
+    settings = json.loads((repo / ".claude" / "settings.json").read_text())
+    assert settings["model"] == "x"
+    assert len(settings["hooks"]["PreToolUse"]) == 1
+
+
+def test_not_a_git_repo_is_allowed(tmp_path, monkeypatch):
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps({"tool_name": "Write", "tool_input": {}})))
+    assert main(["--repo", str(tmp_path), "claude-hook"]) == 0