agentsguard 0.2.0__tar.gz

agentsguard-0.2.0/LICENSE

@@ -0,0 +1,46 @@
+AgentGuard — Proprietary Software License
+Copyright (c) 2026 Ismail Lamdouar. All rights reserved.
+
+IMPORTANT — READ CAREFULLY. This is a proprietary, source-available license.
+The source code of this package is published so that it can be installed and
+inspected. Publication does NOT place it in the public domain and does NOT
+grant any rights beyond those stated below.
+
+1. Grant of use.
+   You are granted a limited, non-exclusive, non-transferable, revocable license
+   to download and install the AgentGuard command-line software (the "Software")
+   and to run it for your own personal or internal business use as a client of
+   the AgentGuard service.
+
+2. Restrictions. You may NOT, without prior written permission from the copyright
+   holder:
+   (a) copy, redistribute, republish, sublicense, sell, rent, or lease the
+       Software or any substantial portion of its source code;
+   (b) modify, adapt, translate, or create derivative works of the Software, or
+       use its source code (in whole or in part) in another product or service;
+   (c) operate, host, or offer a competing or substitute relay/backend service
+       using the Software or knowledge derived from its source code;
+   (d) remove or alter any copyright, trademark, or other proprietary notices.
+
+3. Reverse engineering. The source is provided for transparency and to enable
+   installation. Reading it is permitted; using it to clone, reimplement, or
+   circumvent the AgentGuard service or its security controls is not.
+
+4. Ownership. The Software is licensed, not sold. All title, ownership, and
+   intellectual property rights in and to the Software remain with the copyright
+   holder.
+
+5. No warranty. 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.
+
+6. Limitation of liability. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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.
+
+7. Termination. This license terminates automatically if you breach any term.
+   On termination you must cease all use and destroy all copies of the Software.
+
+For commercial licensing, redistribution rights, or permissions beyond this
+license, contact: lamdouarismail@gmail.com

agentsguard-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: agentsguard
+Version: 0.2.0
+Summary: Approve or deny your AI coding agent's risky commands from your phone, with an audit trail.
+Author: AgentGuard
+License: Proprietary
+Project-URL: Homepage, https://github.com/ismailLamdouar/agentguard
+Project-URL: Issues, https://github.com/ismailLamdouar/agentguard/issues
+Keywords: claude,claude-code,ai-agent,approval,human-in-the-loop,telegram,guardrail,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: qrcode>=7.4
+Provides-Extra: car
+Requires-Dist: gTTS>=2.3; extra == "car"
+Dynamic: license-file
+
+# AgentGuard
+
+**A guardrail layer for autonomous coding agents.** AgentGuard classifies the risk of
+every shell command and file edit your AI coding agent attempts, routes the risky ones to
+your phone for approval, and — critically — **denies by default** when no one responds.
+Every decision is logged.
+
+> Not a remote-control app. Anthropic's
+> [Remote Control](https://code.claude.com/docs/en/remote-control) already lets you drive a
+> Claude session from your phone. AgentGuard is the *policy layer* underneath: it decides
+> what an agent is *allowed* to do, enforces protected files unconditionally, fails safe,
+> and is built to gate **any** agent — not just one vendor's.
+
+## Why it exists
+
+Native permission prompts (and Remote Control's mirrored version of them) ask "allow this?"
+with no risk model, no protected-file enforcement, and no fail-safe: ignore the prompt and
+nothing is denied. AgentGuard adds the missing governance layer:
+
+| | Native prompt / Remote Control | AgentGuard |
+|---|---|---|
+| Risk classification | — | CRITICAL → LOW, defaults to "ask" |
+| Protected files (`.env`, CI, lockfiles, `.claude/`) | — | Always re-affirm, bypass auto-allow |
+| No-response behavior | nothing denied | **default-deny** (fail-safe timeout) |
+| Phone-set guards / auto-rules | — | yes |
+| Audit trail | — | every classify/approve/deny logged |
+
+## How it works
+
+A `PreToolUse` hook intercepts the agent's tool call, a classifier scores it, and:
+
+- **LOW** → auto-approve.
+- **CRITICAL** → auto-deny.
+- **MEDIUM / HIGH** → sent to your phone with a diff/snippet; blocks until you decide.
+- **Protected file** (gate config, secrets, supply-chain/CI) → always reaches you, regardless of score.
+- **No decision within the timeout** → **deny** (fail-safe).
+
+## Install
+
+```bash
+pip install agentsguard            # the CLI command is `agentguard`
+agentguard install-hooks          # wire hooks into this project (.claude/settings.local.json)
+agentguard install-hooks --global # …or all projects (~/.claude/settings.json)
+```
+
+Then restart Claude Code (or run `/hooks`). It's idempotent and leaves any other hooks in place.
+
+## Approval channels
+
+AgentGuard is transport-agnostic — the gate is the product, the channel is a detail:
+
+- **Telegram** (default, zero infra):
+  ```bash
+  agentguard init                 # bot token + chat id
+  ```
+- **Cloud relay + mobile app** (approvals from anywhere):
+  ```bash
+  agentguard pair                 # link this machine to the phone app
+  ```
+
+Quick manual test (no agent needed):
+
+```bash
+agentguard approve-command "git push origin main"   # exits 0 (allow) / 1 (deny)
+```
+
+## Approval modes (`agentguard mode`)
+
+| Mode | Who approves | Use when |
+|------|--------------|----------|
+| `phone` (default) | **Only your phone.** The local popup is suppressed — the hook tells Claude Code allow/deny directly, so work continues the instant you tap. | You're away, or don't want anyone at the keyboard approving for you. |
+| `laptop` | **Only the local prompt.** No phone notifications; the hook steps aside. | You're at the desk and don't want phone pings. |
+
+`agentguard mode laptop` takes effect immediately (read at runtime).
+
+## Claude Code hook
+
+`install-hooks` wires the gating + notification hooks with the correct local path filled in.
+The gating hook looks like:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "agentguard hook --timeout 1800", "timeout": 1800 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **Critical invariant:** the inner `--timeout` must be **≤** the outer `"timeout"`, or Claude
+  Code kills the hook before your phone can respond. `install-hooks` keeps them matched.
+- **Hook *config* changes** take effect only after restarting Claude Code (snapshotted at
+  session start). **Hook *code*** is live with an editable install.
+
+## Other commands
+
+```bash
+agentguard logs -n 20      # activity timeline
+agentguard pending         # is a command awaiting me, or did it stop?
+agentguard resume          # lift a Stop kill-switch
+agentguard instructions    # show instructions sent from the phone
+```
+
+## Storage
+
+All state lives in `~/.agentguard/`: `config.json`, `approvals.json`, `instructions.json`,
+`audit_log.json`.
+
+## License
+
+Proprietary. See [LICENSE](LICENSE).

agentsguard-0.2.0/README.md

@@ -0,0 +1,117 @@
+# AgentGuard
+
+**A guardrail layer for autonomous coding agents.** AgentGuard classifies the risk of
+every shell command and file edit your AI coding agent attempts, routes the risky ones to
+your phone for approval, and — critically — **denies by default** when no one responds.
+Every decision is logged.
+
+> Not a remote-control app. Anthropic's
+> [Remote Control](https://code.claude.com/docs/en/remote-control) already lets you drive a
+> Claude session from your phone. AgentGuard is the *policy layer* underneath: it decides
+> what an agent is *allowed* to do, enforces protected files unconditionally, fails safe,
+> and is built to gate **any** agent — not just one vendor's.
+
+## Why it exists
+
+Native permission prompts (and Remote Control's mirrored version of them) ask "allow this?"
+with no risk model, no protected-file enforcement, and no fail-safe: ignore the prompt and
+nothing is denied. AgentGuard adds the missing governance layer:
+
+| | Native prompt / Remote Control | AgentGuard |
+|---|---|---|
+| Risk classification | — | CRITICAL → LOW, defaults to "ask" |
+| Protected files (`.env`, CI, lockfiles, `.claude/`) | — | Always re-affirm, bypass auto-allow |
+| No-response behavior | nothing denied | **default-deny** (fail-safe timeout) |
+| Phone-set guards / auto-rules | — | yes |
+| Audit trail | — | every classify/approve/deny logged |
+
+## How it works
+
+A `PreToolUse` hook intercepts the agent's tool call, a classifier scores it, and:
+
+- **LOW** → auto-approve.
+- **CRITICAL** → auto-deny.
+- **MEDIUM / HIGH** → sent to your phone with a diff/snippet; blocks until you decide.
+- **Protected file** (gate config, secrets, supply-chain/CI) → always reaches you, regardless of score.
+- **No decision within the timeout** → **deny** (fail-safe).
+
+## Install
+
+```bash
+pip install agentsguard            # the CLI command is `agentguard`
+agentguard install-hooks          # wire hooks into this project (.claude/settings.local.json)
+agentguard install-hooks --global # …or all projects (~/.claude/settings.json)
+```
+
+Then restart Claude Code (or run `/hooks`). It's idempotent and leaves any other hooks in place.
+
+## Approval channels
+
+AgentGuard is transport-agnostic — the gate is the product, the channel is a detail:
+
+- **Telegram** (default, zero infra):
+  ```bash
+  agentguard init                 # bot token + chat id
+  ```
+- **Cloud relay + mobile app** (approvals from anywhere):
+  ```bash
+  agentguard pair                 # link this machine to the phone app
+  ```
+
+Quick manual test (no agent needed):
+
+```bash
+agentguard approve-command "git push origin main"   # exits 0 (allow) / 1 (deny)
+```
+
+## Approval modes (`agentguard mode`)
+
+| Mode | Who approves | Use when |
+|------|--------------|----------|
+| `phone` (default) | **Only your phone.** The local popup is suppressed — the hook tells Claude Code allow/deny directly, so work continues the instant you tap. | You're away, or don't want anyone at the keyboard approving for you. |
+| `laptop` | **Only the local prompt.** No phone notifications; the hook steps aside. | You're at the desk and don't want phone pings. |
+
+`agentguard mode laptop` takes effect immediately (read at runtime).
+
+## Claude Code hook
+
+`install-hooks` wires the gating + notification hooks with the correct local path filled in.
+The gating hook looks like:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "agentguard hook --timeout 1800", "timeout": 1800 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **Critical invariant:** the inner `--timeout` must be **≤** the outer `"timeout"`, or Claude
+  Code kills the hook before your phone can respond. `install-hooks` keeps them matched.
+- **Hook *config* changes** take effect only after restarting Claude Code (snapshotted at
+  session start). **Hook *code*** is live with an editable install.
+
+## Other commands
+
+```bash
+agentguard logs -n 20      # activity timeline
+agentguard pending         # is a command awaiting me, or did it stop?
+agentguard resume          # lift a Stop kill-switch
+agentguard instructions    # show instructions sent from the phone
+```
+
+## Storage
+
+All state lives in `~/.agentguard/`: `config.json`, `approvals.json`, `instructions.json`,
+`audit_log.json`.
+
+## License
+
+Proprietary. See [LICENSE](LICENSE).

agentsguard-0.2.0/agentguard/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

agentsguard-0.2.0/agentguard/approval_engine.py

@@ -0,0 +1,194 @@
+import os
+from datetime import datetime
+
+from . import guards, presets, risk_engine, telegram_bot
+from .audit import log_event, now_iso
+from .config import load_config
+from .storage import add_approval, add_instruction, list_approvals
+
+DEFAULT_TIMEOUT = 120
+DEFAULT_DEDUP_WINDOW = 10
+
+# Decisions that count as "already answered" for idempotency purposes.
+_FINAL_DECISIONS = (
+    "approved", "denied", "stopped", "auto_approved", "auto_denied", "timeout",
+    "allow_all", "guard_denied",
+)
+
+
+_RISK_RANK = {risk_engine.LOW: 0, risk_engine.MEDIUM: 1, risk_engine.HIGH: 2, risk_engine.CRITICAL: 3}
+
+
+def _rank(level: str) -> int:
+    return _RISK_RANK.get(level, 1)
+
+
+class NotConfigured(Exception):
+    pass
+
+
+def _recent_decision(command: str, window_seconds: int):
+    """Return the most recent final decision for an identical command made within
+    `window_seconds`, else None. Lets a duplicate hook fire reuse a just-made
+    decision instead of posting a second, stale prompt."""
+    if window_seconds <= 0:
+        return None
+    now = datetime.now()
+    for rec in reversed(list_approvals()):
+        if rec.get("command") != command:
+            continue
+        decision = rec.get("decision")
+        if decision not in _FINAL_DECISIONS:
+            continue
+        ts = rec.get("timestamp")
+        try:
+            when = datetime.fromisoformat(ts) if ts else None
+        except ValueError:
+            when = None
+        if when is None:
+            return None
+        # The newest matching command decides it: reuse only if still fresh.
+        return decision if (now - when).total_seconds() <= window_seconds else None
+    return None
+
+
+def _save_instruction(text: str) -> None:
+    add_instruction(text, now_iso())
+    log_event("instruction_added", text=text)
+    # A "don't touch X" instruction becomes an enforced guard.
+    keyword = guards.maybe_add_from_instruction(text)
+    if keyword:
+        log_event("guard_added", keyword=keyword, text=text)
+        cfg = load_config()
+        token, chat_id = cfg.get("telegram_bot_token"), cfg.get("telegram_chat_id")
+        if token and chat_id:
+            try:
+                telegram_bot.send_message(
+                    token, chat_id,
+                    f"🛡️ *Guard set* — I'll block commands touching `{keyword}`.",
+                )
+            except Exception:
+                pass
+
+
+def request_approval(command: str, timeout: int = DEFAULT_TIMEOUT, risk_override: str = None, tool_name: str = None, details: str = None, prompt: str = None, session_id: str = None) -> str:
+    """Run the full approval flow for a command. Returns one of:
+    'approved', 'denied', 'stopped', 'auto_approved', 'auto_denied', 'timeout'.
+
+    `risk_override` forces the severity instead of classifying `command` — used
+    for non-Bash tools (Write/Edit), whose subject string isn't a shell command
+    and must not be run through the regex classifier (a path like `cat.py` would
+    falsely match LOW and auto-approve).
+    """
+    risk = risk_override or risk_engine.classify(command)
+    log_event("approval_requested", command=command, risk=risk)
+
+    cfg = load_config()
+
+    # Cloud-relay backend: when paired with the relay (`backend: "relay"`), route
+    # the whole approval through it (guards, auto-rules, push, and the phone
+    # decision all live server-side). The Telegram path below is the alternative.
+    from . import relay_client
+
+    if relay_client.is_relay_configured(cfg):
+        kind = "Shell Command" if not tool_name or tool_name == "Bash" else "File Edit"
+        decision = relay_client.request_approval_relay(command, risk, kind=kind, timeout=timeout, cfg=cfg, details=details, prompt=prompt, session_id=session_id)
+        add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": decision})
+        log_event("relay_decision", command=command, risk=risk, decision=decision)
+        return decision
+
+    # Phone-set guards ("Do not touch auth") hard-block any matching command,
+    # regardless of risk — before it can be auto-approved or reach the phone.
+    guard = guards.violated_by(command)
+    if guard:
+        add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "guard_denied"})
+        log_event("guard_blocked", command=command, risk=risk, guard=guard.get("keyword"))
+        token, chat_id = cfg.get("telegram_bot_token"), cfg.get("telegram_chat_id")
+        if token and chat_id:
+            try:
+                telegram_bot.send_message(
+                    token, chat_id,
+                    f"🛡️ *Blocked by your guard* (_{guard.get('text')}_):\n```\n{command}\n```",
+                )
+            except Exception:
+                pass
+        return "guard_denied"
+
+    mirror_all = bool(cfg.get("mirror_all", False))
+    car_mode = bool(cfg.get("car_mode", False))
+
+    if car_mode:
+        # Car Mode: auto-approve anything below the ask threshold so routine
+        # commands don't interrupt you while driving; only risk >= threshold
+        # reaches the phone (CRITICAL is asked, not auto-denied, here).
+        threshold = cfg.get("car_ask_above", "high")
+        if _rank(risk) < _rank(threshold):
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_approved"})
+            log_event("car_auto_approved", command=command, risk=risk, threshold=threshold)
+            return "auto_approved"
+    elif not mirror_all:
+        # In mirror mode every command is forwarded to the phone — the auto-approve
+        # (LOW) and auto-deny (CRITICAL) shortcuts are skipped so nothing is decided
+        # without you.
+        if risk == risk_engine.LOW:
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_approved"})
+            log_event("auto_approved", command=command, risk=risk)
+            return "auto_approved"
+
+        if risk == risk_engine.CRITICAL:
+            add_approval({"timestamp": now_iso(), "command": command, "risk": risk, "decision": "auto_denied"})
+            log_event("auto_denied", command=command, risk=risk, reason="critical_default")
+            return "auto_denied"
+
+    token = cfg.get("telegram_bot_token")
+    chat_id = cfg.get("telegram_chat_id")
+    if not token or not chat_id:
+        raise NotConfigured("Run `agentguard init` first.")
+
+    # Idempotency: a duplicate hook fire for a command decided moments ago reuses
+    # that decision instead of posting a second, stale Approve/Deny prompt.
+    window = int(cfg.get("dedup_window_seconds", DEFAULT_DEDUP_WINDOW))
+    prior = _recent_decision(command, window)
+    if prior is not None:
+        log_event("dedup_reused", command=command, risk=risk, decision=prior)
+        verb = "approved" if prior in ("approved", "auto_approved") else prior
+        try:
+            telegram_bot.send_message(
+                token,
+                chat_id,
+                f"↩️ *Already answered* ({verb}) — not asking again:\n```\n{command}\n```",
+            )
+        except Exception:
+            pass
+        return prior
+
+    quick = presets.for_command(command)
+    car_mode = bool(cfg.get("car_mode"))
+    openai_key = cfg.get("openai_api_key") or os.environ.get("OPENAI_API_KEY")
+    message_id = telegram_bot.send_approval_request(token, chat_id, command, risk, presets=quick, allow_all_label=tool_name)
+    log_event("telegram_sent", command=command, risk=risk, message_id=message_id)
+    if car_mode and cfg.get("car_speak", True):
+        telegram_bot.speak(token, chat_id, f"Approval needed. {risk} risk. Command: {command}. Reply approve, deny, or stop.")
+
+    decision = telegram_bot.wait_for_decision(
+        token=token,
+        chat_id=chat_id,
+        message_id=message_id,
+        command=command,
+        risk=risk,
+        timeout=timeout,
+        on_instruction=_save_instruction,
+        presets=quick,
+        allow_all_label=tool_name,
+        car_mode=car_mode,
+        openai_key=openai_key,
+    )
+
+    add_approval({
+        "timestamp": now_iso(),
+        "command": command,
+        "risk": risk,
+        "decision": decision,
+    })
+    log_event(decision, command=command, risk=risk)
+    return decision

agentsguard-0.2.0/agentguard/audit.py

@@ -0,0 +1,31 @@
+import json
+from datetime import datetime
+
+from .config import AUDIT_FILE, ensure_dir
+
+
+def now_iso() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def log_event(event: str, **fields) -> None:
+    ensure_dir()
+    record = {"timestamp": now_iso(), "event": event, **fields}
+    try:
+        items = json.loads(AUDIT_FILE.read_text(encoding="utf-8"))
+        if not isinstance(items, list):
+            items = []
+    except (json.JSONDecodeError, FileNotFoundError):
+        items = []
+    items.append(record)
+    AUDIT_FILE.write_text(json.dumps(items, indent=2), encoding="utf-8")
+
+
+def load_log() -> list:
+    if not AUDIT_FILE.exists():
+        return []
+    try:
+        data = json.loads(AUDIT_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else []
+    except json.JSONDecodeError:
+        return []