agent-write-gate 0.1.0__py3-none-any.whl

agent_write_gate-0.1.0.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: agent-write-gate
+Version: 0.1.0
+Summary: Agent-hook safety gate for AI-written code -- blocks bidi/invisible Unicode and CJK corruption at the write boundary
+License: MIT
+Keywords: agent,hook,safety,unicode,cjk,llm,claude-code,codex,pre-commit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: cjk
+Requires-Dist: mojihen>=0.1; extra == "cjk"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# agentgate
+
+An agent-hook safety gate for AI-written code. Wire it into Claude Code or Codex
+as a hook; it runs a battery of deterministic checks on the text an agent is about
+to write (PreToolUse) or just wrote (PostToolUse) and either blocks the write or
+hands the model a structured feedback blob so the loop self-corrects without a
+human round-trip.
+
+## Problem
+
+AI coding agents write files directly. They introduce defect classes that
+traditional linters and CI were not built to catch:
+
+- **Valid-but-wrong CJK** -- a real but wrong kanji/hanzi/hangul (mojihen's
+  domain; grep and unit tests pass it as false-green).
+- **Bidi / invisible Unicode** -- Trojan-Source bidi overrides and invisible
+  characters smuggled into source identifiers.
+
+Both have standalone CLIs that run in CI. What is missing is a single hook at
+the agent write boundary that (a) speaks the agents' hook protocols, (b) applies
+one severity-to-action policy across checks, and (c) returns a model-readable
+feedback blob so the agent rewrites itself.
+
+## Positioning (honest)
+
+agentgate is not a new category -- Claude Code and Codex already expose hook
+frameworks. agentgate is the packaged, cross-agent gate that bundles
+AI-write-specific checks, normalizes the two agents' payloads, centralizes
+block/warn policy, and ships an open check registry so the set grows without
+forking. The ecosystem value is the gate + registry standard, plus composing the
+sibling engine mojihen, not any single linter.
+
+## Coverage limits
+
+agentgate only sees writes that flow through a hooked tool call. It does NOT see,
+and makes no claim about:
+
+- Files written by shell commands the agent runs (`echo >`, `sed -i`, codegen).
+- Pre-existing files, generated artifacts, or out-of-band edits.
+- Editor/IDE agents that do not emit the supported hook payloads.
+- Codex tool paths other than `apply_patch` (best-effort; fail-open otherwise).
+- Anything a PostToolUse hook is asked to undo -- it cannot roll back a completed
+  write, only report it back to the model.
+
+## M1 built-in checks
+
+### unicode (stdlib, always available)
+
+- **AG-BIDI** (high, always block): bidi control characters U+202A-U+202E,
+  U+2066-U+2069. These are the Trojan-Source vectors with essentially no
+  legitimate use in source files.
+- **AG-INVIS** (high, code context only): invisible chars (U+200B zero-width
+  space, U+2060 word joiner, U+FEFF stray BOM, U+00AD soft hyphen) flagged only
+  when the file has a code extension AND the char is inside an identifier/string
+  run. U+200C/U+200D (ZWNJ/ZWJ) and U+200E/U+200F (LRM/RLM) are NOT flagged
+  by default -- they are legitimate in Arabic/Persian/Indic text and emoji ZWJ
+  sequences. Strict mode (`unicode.strict_zerowidth = true`) adds ZWNJ/ZWJ only
+  inside ASCII-identifier runs.
+- **AG-HOMO** (medium, opt-in): Latin-looking Cyrillic/Greek codepoints inside
+  an otherwise-ASCII identifier. Off by default.
+
+### cjk (requires mojihen extra)
+
+Embeds `mojihen.detect.run_detectors` to catch known LLM CJK corruption: a
+real but wrong kanji/hanzi that grep and unit tests pass as false-green (rule
+MH001 and others). Disabled by default so the stdlib-only core installs and runs
+out of the box.
+
+## Install
+
+Core (stdlib-only, unicode check):
+
+```sh
+pip install agent-write-gate
+```
+
+With CJK check (requires mojihen):
+
+```sh
+pip install agent-write-gate[cjk]
+```
+
+Then enable in config:
+
+```toml
+# agentgate.toml
+[checks]
+cjk = true
+```
+
+## CLI
+
+```sh
+# Primary: agent hook entrypoint (pipe JSON from agent hook system)
+agentgate hook --stdin
+
+# Scan files (CI / manual audit)
+agentgate scan src/ --format tty|json|sarif
+
+# List checks and their status
+agentgate checks
+
+# Version
+agentgate --version
+```
+
+Exit codes:
+- `hook`: 0 = allow; 2 = block (deny in Pre / feedback in Post) or error.
+- `scan`: 0 = no blocking findings; 1 = blocking findings; 2 = error.
+
+## Hook setup: Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{"type": "command", "command": "agentgate hook --stdin"}]
+      }
+    ]
+  }
+}
+```
+
+**PreToolUse** (exit 2) denies the tool call -- the write never happens.
+**PostToolUse** (exit 2) surfaces feedback to the model after the write.
+Only PreToolUse provides true prevention. See `hooks/claude-code.md`.
+
+## Hook setup: Codex
+
+Only `apply_patch` is supported (Codex's primary write tool):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "apply_patch",
+        "hooks": [{"type": "command", "command": "agentgate hook --stdin"}]
+      }
+    ]
+  }
+}
+```
+
+See `hooks/codex.md` for PostToolUse setup and coverage limits.
+
+## pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/hryoma1217/agentgate
+    rev: v0.1.0
+    hooks:
+      - id: agentgate
+```
+
+The bidi / invisible-Unicode checks work out of the box. The CJK corruption
+check is **off by default**; if you enable it (`[checks.cjk] enabled = true`), the
+hook also needs `mojihen` in pre-commit's isolated env — add it via
+`additional_dependencies`:
+
+```yaml
+      - id: agentgate
+        additional_dependencies: ["agent-write-gate[cjk]"]
+```
+
+## Configuration
+
+`agentgate.toml` or `[tool.agentgate]` in `pyproject.toml`. Falls back to
+defaults when no config file is found.
+
+```toml
+# Unicode checks are ON by default; the CJK check is OFF by default.
+# Enable CJK only if you installed the `agent-write-gate[cjk]` extra.
+[checks.cjk]
+enabled        = false
+min_confidence = "high"
+
+[checks.unicode]
+enabled                = true
+homoglyph              = false
+strict_zerowidth       = false
+allow_bidi_suppression = false
+code_extensions = [
+  ".py", ".js", ".ts", ".go", ".rs", ".java",
+  ".c", ".cpp", ".rb", ".php", ".sh", ".sql"
+]
+
+[policy]
+high   = "block"
+medium = "warn"
+low    = "ignore"
+```
+
+## Suppression
+
+Rule-specific only: `agentgate: ignore[AG-INVIS]` on the offending line.
+**There is no bare `agentgate: ignore`** -- that would let a model launder
+violations. AG-BIDI is not suppressible unless `allow_bidi_suppression = true`.
+
+## Model-readable block report
+
+When a write is blocked, stderr looks like:
+
+```
+agentgate: BLOCKED -- 2 issue(s) to fix before this write
+
+  app.py:3:18  cjk/MH001 HIGH  '闾'  -> likely: 閾
+      '闾' is a known LLM corruption (likely intended: 閾) ...
+  app.py:5:1   unicode/AG-BIDI HIGH  U+202E RIGHT-TO-LEFT OVERRIDE
+      Remove the bidi control char; it visually reorders source.
+
+  Fix these and re-emit.
+```
+
+The model sees this as a structured remediation signal and issues a corrective
+write without human intervention.
+
+## Relationship to mojihen
+
+mojihen is the CJK engine (its own PyPI package, independently useful).
+agentgate is the cross-agent gate that composes it (optional extra
+`agent-write-gate[cjk]`) with the stdlib Unicode-safety check, under one policy and
+one model-readable feedback contract. Two focused packages; the gate + open
+registry is the ecosystem layer.
+
+## Open registry
+
+Third-party checks can be registered:
+
+```python
+from agentgate.registry import register
+
+def my_check(event, cfg):
+    # event: WriteEvent, cfg: GateConfig
+    # return List[Issue]
+    return []
+
+register("my-check", my_check)
+```
+
+## License
+
+MIT

agent_write_gate-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+agent_write_gate-0.1.0.dist-info/licenses/LICENSE,sha256=EFPLivHeuSpMRblwoRojAy4LPIQWwUUv5AloeiXURK8,1067
+agentgate/__init__.py,sha256=FSXOZSQw9IjapLmsC49eP4vrqIp1pYE4NLyHtF3_gjM,122
+agentgate/adapter.py,sha256=rSqNJEpwPfGhZ8-BVVKVeG11VToHMhExQOrK2qAgn28,4819
+agentgate/apply_patch.py,sha256=Y7YF917EQBDIVCoJz7Vyt_GwVSo8e-jiL1_y9C0LD3g,2368
+agentgate/cli.py,sha256=N6eyN-afmQHslzbkXwCyoFEYlUjtyyBxqpxo94lTZMk,17599
+agentgate/config.py,sha256=ZLYk9UQl9kVsx_1X8xLkerXm2pm6A9Kc6HMWfu5G4Xg,5843
+agentgate/model.py,sha256=7YRVsmQT9duIja2Cn3XXPjExqc501tYQX3tPJ747Na0,939
+agentgate/policy.py,sha256=UlvueIacLdcjYTQk4XKknRy2z54FddDRlhR3gvUDhhg,2945
+agentgate/registry.py,sha256=XmDMBmNLNs_HRhc3LIPN1MJPELM5mLp3nXEowk3tVpU,1859
+agentgate/report.py,sha256=H0jmFhVFIMxMWSjEmeDZTtsyw1_sSlZs6BZefE-uI5g,7866
+agentgate/checks/__init__.py,sha256=z1LFE7PdlelmBfqVFGt-GECPwlfl79keKZsIpEYFdlQ,50
+agentgate/checks/cjk.py,sha256=IjFlJ21NNeABHwpeIab2xQfTE0-S9qSnjuc9GpvSYQA,2547
+agentgate/checks/unicode_safety.py,sha256=_920jV6YW3B5Blyjiv3nNHsuGGhHytPFn77qjTIKW6A,10846
+agent_write_gate-0.1.0.dist-info/METADATA,sha256=TINKwXOPM7vIX31RBGVAE2FfrUvA2vyksh2W4PPc_Qc,8589
+agent_write_gate-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_write_gate-0.1.0.dist-info/entry_points.txt,sha256=Gfb2Xz_dlF6OF6MhPrV3mmWri0gFeZC0DWVHmGiXOhM,49
+agent_write_gate-0.1.0.dist-info/top_level.txt,sha256=qWUC8JQwEvSXwMD-j8F0kB0LIDQhef7EPRPGeosKWb4,10
+agent_write_gate-0.1.0.dist-info/RECORD,,

agent_write_gate-0.1.0.dist-info/WHEEL

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

agent_write_gate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentgate = agentgate.cli:main

agent_write_gate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hryoma1217
+
+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.

agent_write_gate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentgate

agentgate/__init__.py

@@ -0,0 +1,5 @@
+"""agentgate -- agent-hook safety gate for AI-written code."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

agentgate/adapter.py

@@ -0,0 +1,142 @@
+"""adapter.py -- Normalize stdin JSON hook payloads into WriteEvent.
+
+Supports three payload shapes:
+  1. Claude Code: {hook_event_name, tool_name, tool_input:{file_path, content|new_string}}
+  2. Codex apply_patch: tool_input.command containing *** Begin Patch envelope
+  3. Generic fallback: {file_path|path, content|text|new_string} at top level or tool_input
+
+Never raises on bad input -- tolerant extraction throughout.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from .apply_patch import parse_apply_patch
+from .model import WriteEvent
+
+
+def _extract_content(obj: Dict[str, Any]) -> str:
+    """Extract content text from a tool_input-like dict."""
+    return (
+        obj.get("content")
+        or obj.get("new_string")
+        or obj.get("text")
+        or ""
+    )
+
+
+def _extract_path(obj: Dict[str, Any]) -> str:
+    """Extract file path from a tool_input-like dict."""
+    return (
+        obj.get("file_path")
+        or obj.get("path")
+        or "<stdin>"
+    )
+
+
+def _parse_phase(hook_event_name: Optional[str]) -> str:
+    if not hook_event_name:
+        return "unknown"
+    hen = hook_event_name.lower()
+    if "pre" in hen:
+        return "pre"
+    if "post" in hen:
+        return "post"
+    return "unknown"
+
+
+def from_stdin_json(raw: str) -> WriteEvent:
+    """Parse a raw stdin string into a WriteEvent.
+
+    Returns a WriteEvent with empty content when nothing can be extracted.
+    Caller should check event.content and exit 0 when empty (nothing to gate).
+    """
+    if not raw or not raw.strip():
+        return WriteEvent(agent="generic", phase="unknown", tool="unknown",
+                          file_path="<stdin>", content="")
+
+    try:
+        payload = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return WriteEvent(agent="generic", phase="unknown", tool="unknown",
+                          file_path="<stdin>", content="")
+
+    if not isinstance(payload, dict):
+        return WriteEvent(agent="generic", phase="unknown", tool="unknown",
+                          file_path="<stdin>", content="")
+
+    # -----------------------------------------------------------------------
+    # 1. Claude Code shape: has hook_event_name + tool_name
+    # -----------------------------------------------------------------------
+    hook_event_name = payload.get("hook_event_name")
+    tool_name = payload.get("tool_name")
+
+    if hook_event_name and tool_name:
+        phase = _parse_phase(hook_event_name)
+        tool_input = payload.get("tool_input") or {}
+        if not isinstance(tool_input, dict):
+            tool_input = {}
+
+        file_path = _extract_path(tool_input)
+        content = _extract_content(tool_input)
+
+        return WriteEvent(
+            agent="claude-code",
+            phase=phase,
+            tool=str(tool_name),
+            file_path=file_path,
+            content=content,
+        )
+
+    # -----------------------------------------------------------------------
+    # 2. Codex shape: tool_input.command containing apply_patch
+    # -----------------------------------------------------------------------
+    tool_input = payload.get("tool_input")
+    if isinstance(tool_input, dict):
+        command = tool_input.get("command")
+
+        # command may be a string or a list (argv)
+        if isinstance(command, list):
+            command_str = " ".join(str(c) for c in command)
+        elif isinstance(command, str):
+            command_str = command
+        else:
+            command_str = ""
+
+        if command_str and "*** Begin Patch" in command_str:
+            file_path, added_text = parse_apply_patch(command_str)
+            return WriteEvent(
+                agent="codex",
+                phase=_parse_phase(payload.get("hook_event_name")),
+                tool="apply_patch",
+                file_path=file_path or "<stdin>",
+                content=added_text,
+            )
+
+        # tool_input present but not apply_patch -- try generic extraction from tool_input
+        file_path = _extract_path(tool_input)
+        content = _extract_content(tool_input)
+        if content:
+            return WriteEvent(
+                agent="generic",
+                phase=_parse_phase(payload.get("hook_event_name")),
+                tool="unknown",
+                file_path=file_path,
+                content=content,
+            )
+
+    # -----------------------------------------------------------------------
+    # 3. Generic / fallback: content at top level
+    # -----------------------------------------------------------------------
+    file_path = _extract_path(payload)
+    content = _extract_content(payload)
+
+    return WriteEvent(
+        agent="generic",
+        phase="unknown",
+        tool="unknown",
+        file_path=file_path,
+        content=content,
+    )

agentgate/apply_patch.py

@@ -0,0 +1,74 @@
+"""apply_patch.py -- Parse a Codex apply_patch envelope.
+
+Handles the envelope format:
+  *** Begin Patch
+  *** Add File: path/to/file
+  +added line
+  +another added line
+  *** Update File: path/to/other
+  context line
+  +added line
+   more context
+  *** End Patch
+
+Returns (path, added_text) where:
+  - path is the first Add File or Update File path found
+  - added_text is the joined added lines ('+'-prefixed, excluding '+++' diff headers)
+
+Returns ("", "") if the envelope is missing or cannot be parsed.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+
+def parse_apply_patch(command: str) -> Tuple[str, str]:
+    """Parse a Codex apply_patch command string.
+
+    Returns (file_path, added_text).  On any parse failure returns ("", "").
+    """
+    if not isinstance(command, str):
+        return ("", "")
+
+    # Locate envelope boundaries
+    begin_marker = "*** Begin Patch"
+    end_marker = "*** End Patch"
+
+    begin_idx = command.find(begin_marker)
+    if begin_idx == -1:
+        return ("", "")
+
+    end_idx = command.find(end_marker, begin_idx)
+    if end_idx == -1:
+        # Accept unterminated envelope -- take everything after begin
+        envelope = command[begin_idx + len(begin_marker):]
+    else:
+        envelope = command[begin_idx + len(begin_marker):end_idx]
+
+    lines = envelope.splitlines()
+
+    file_path = ""
+    added_lines = []
+
+    for line in lines:
+        if line.startswith("*** Add File:"):
+            candidate = line[len("*** Add File:"):].strip()
+            if candidate and not file_path:
+                file_path = candidate
+        elif line.startswith("*** Update File:"):
+            candidate = line[len("*** Update File:"):].strip()
+            if candidate and not file_path:
+                file_path = candidate
+        elif line.startswith("*** Delete File:"):
+            # Deletions have no added content; note path but no lines
+            candidate = line[len("*** Delete File:"):].strip()
+            if candidate and not file_path:
+                file_path = candidate
+        elif line.startswith("+") and not line.startswith("+++"):
+            # Added line: strip the leading '+'
+            added_lines.append(line[1:])
+        # Context lines (no prefix or space prefix) and removed lines ('-') are ignored
+
+    added_text = "\n".join(added_lines)
+    return (file_path, added_text)

agentgate/checks/__init__.py

@@ -0,0 +1 @@
+"""checks -- Built-in agentgate check modules."""

agentgate/checks/cjk.py

@@ -0,0 +1,81 @@
+"""cjk.py -- CJK corruption check using mojihen.
+
+Embeds mojihen.detect.run_detectors per line at cfg.cjk.min_confidence.
+Maps mojihen Finding -> agentgate Issue.
+
+If mojihen is not importable AND cjk is enabled, raises RuntimeError with
+a clear install message. This error is caught at startup (never silent).
+"""
+
+from __future__ import annotations
+
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..model import WriteEvent, Issue
+    from ..config import GateConfig
+
+from ..model import Issue
+
+
+def _require_mojihen():
+    """Import mojihen and return (run_detectors, Corpus, load_corpus).
+
+    Raises RuntimeError with install instructions if mojihen is absent.
+    """
+    try:
+        from mojihen.detect import run_detectors, CONFIDENCE_RANK  # type: ignore
+        from mojihen.corpus import load_corpus  # type: ignore
+        return run_detectors, CONFIDENCE_RANK, load_corpus
+    except ImportError as exc:
+        raise RuntimeError(
+            "cjk check enabled but mojihen is not installed.\n"
+            "  Install it with:  pip install agent-write-gate[cjk]\n"
+            "  Or disable it in config:  [checks]  cjk = false\n"
+            f"  (Original error: {exc})"
+        ) from exc
+
+
+def run(event: "WriteEvent", cfg: "GateConfig") -> List["Issue"]:
+    """Run CJK corruption check using mojihen. Returns list of Issues."""
+    run_detectors, CONFIDENCE_RANK, load_corpus = _require_mojihen()
+
+    content = event.content
+    if not content:
+        return []
+
+    min_confidence = cfg.cjk.min_confidence
+
+    # Load corpus with defaults
+    corpus = load_corpus([])  # empty list = built-in corpus only
+    allow_set: set = set()
+
+    issues: List[Issue] = []
+    lines = content.splitlines()
+
+    for i, line in enumerate(lines, start=1):
+        findings = run_detectors(
+            line,
+            i,
+            corpus,
+            allow_set,
+            min_confidence=min_confidence,
+        )
+        for f in findings:
+            # Build suggestion from intended list
+            suggestion = ""
+            if f.intended:
+                suggestion = "likely: " + "|".join(f.intended)
+
+            issues.append(Issue(
+                check="cjk",
+                rule_id=f.rule_id,
+                severity="high" if f.confidence == "high" else "medium" if f.confidence == "medium" else "low",
+                line=f.line,
+                col=f.col,
+                message=f.message,
+                excerpt=f.run,
+                suggestion=suggestion,
+            ))
+
+    return issues