@caddis/cli 0.0.0 → 0.1.0

package/LICENSE

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

package/README.md

@@ -1 +1,150 @@
-Placeholder. Install 0.1.0 or later.
+# @caddis/cli
+
+**One command to install, update and diagnose the [caddis](https://github.com/saajunaid/caddis-plugin) dev harness across every coding agent you use.**
+
+```bash
+npx @caddis/cli init      # detect your agents, confirm, install caddis into each
+npx @caddis/cli doctor    # what is installed where, and what to do about it
+```
+
+If you use more than one coding agent, you have more than one place caddis can go stale.
+This CLI is the single front door.
+
+---
+
+## What it does
+
+caddis is a **meta-installer**. It detects the agents on your machine and drives **each one's own
+native install mechanism** — it never reimplements them, and it never installs an agent for you.
+
+| Agent | Detected via | How caddis is installed | v0.1 |
+| --- | --- | --- | --- |
+| **Claude Code** | `claude` on PATH | its plugin marketplace | ✅ |
+| **agy** (Antigravity) | `agy` on PATH | the caddis bundle shipped inside this package | ✅ |
+| **Codex** | `codex` on PATH / `~/.codex` | config merge | v0.2 |
+| **GitHub Copilot** | `copilot` on PATH / `.github/copilot-instructions.md` | config merge | v0.2 |
+
+Codex and Copilot are **detected and reported** in v0.1, never written to. They are file-configured,
+which means supporting them properly requires merging into config you already own — that ships when
+it is safe, not before.
+
+**Absence is graceful.** Missing agents are skipped with a reason, never an error. One agent failing
+never stops the others.
+
+---
+
+## Install
+
+```bash
+npx @caddis/cli <command>      # no install
+npm i -g @caddis/cli           # then just: caddis <command>
+```
+
+Requires **Node >= 20.19**.
+
+---
+
+## Commands
+
+### `caddis doctor`
+
+The one worth knowing. Every agent, the caddis version each actually has, whether that matches what
+this CLI ships, where the version was read from, and the exact command that fixes each gap.
+
+```
+Environment
+  ✓ node 22.14.0
+  • platform win32 x64
+  • @caddis/cli 0.1.0
+  ✓ shipped pool 1.3.39
+      bundle antigravity-plugin @ 1.3.39
+
+Agents
+  ▲ Claude Code — caddis 1.3.38 → 1.3.39 available
+      C:\Users\you\AppData\Roaming\npm\claude.CMD
+      agent version 2.1.220
+      read from `claude plugin list`
+      → caddis update --agent claude
+  ▲ agy (Antigravity) — caddis 1.3.38 → 1.3.39 available
+      ~\.gemini\config\plugins\caddis\plugin.json
+      → caddis update --agent agy
+  • Codex — detected — not yet supported (v0.2)
+
+Summary
+  3 of 4 agents detected · 0 current · 2 stale · 0 not installed
+
+  2 things to fix:
+    • Claude Code has caddis 1.3.38, this CLI ships 1.3.39
+      caddis update --agent claude
+    • agy (Antigravity) has caddis 1.3.38, this CLI ships 1.3.39
+      caddis update --agent agy
+```
+
+`--strict` exits non-zero when something needs fixing (for CI). Detected-but-unsupported agents are
+information, not failures, and never trip `--strict`. `--json` gives machine-readable output.
+
+### `caddis status`
+
+The same facts as a glanceable table. Running bare `caddis` does this.
+
+```
+  caddis  cli 0.1.0  ·  pool 1.3.39
+
+  AGENT              DETECTED  CADDIS  STATE
+  ─────────────────  ────────  ──────  ────────────────
+  Claude Code        yes       1.3.38  update available
+  agy (Antigravity)  yes       1.3.38  update available
+  Codex              yes       —       v0.2
+  GitHub Copilot     no        —       —
+
+  2 agent(s) behind — run caddis update (or caddis doctor for detail)
+```
+
+### `caddis update`
+
+Brings every detected, supported agent up to the caddis version shipped in this CLI, through that
+agent's native mechanism. Agents already current are skipped (`--force` re-drives them).
+
+### `caddis init`
+
+The first run. Detects, shows exactly what it is about to run, asks, then installs. `--yes` skips
+the prompt for CI.
+
+---
+
+## Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | print the exact vendor commands; change nothing |
+| `-y, --yes` | never prompt |
+| `-a, --agent <name...>` | limit to specific agents (`claude`, `agy`, `codex`, `copilot`) |
+| `--json` | machine-readable output (`doctor`, `status`) |
+| `--strict` | exit 1 when something needs fixing (`doctor`) |
+| `--no-update-notifier` | skip the "newer @caddis/cli available" check |
+
+Flags work before or after the subcommand: `caddis update --dry-run` and `caddis --dry-run update`
+are the same.
+
+**Always safe to preview:**
+
+```bash
+$ caddis update --dry-run
+  · Claude Code — dry run — nothing executed
+      would run: claude plugin marketplace update caddis
+      would run: claude plugin update caddis@caddis
+  · agy (Antigravity) — dry run — nothing executed
+      would run: agy plugin install <shipped bundle>
+```
+
+---
+
+## Where the caddis content comes from
+
+The caddis bundle ships **inside this npm package**, versioned in lockstep with the CLI — the caddis
+you install is the caddis you get, with no extra fetch. `doctor` compares each agent's installed
+version against that shipped version; that difference is what "drift" means throughout.
+
+## License
+
+MIT

package/bundles/antigravity-plugin/agents/code-reviewer.md

@@ -0,0 +1,47 @@
+---
+name: code-reviewer
+description: Use this agent to review a diff or set of changes for correctness, security, and convention adherence. Use proactively after a phase is green and before commit/merge. Reads the diff and relevant files in its own context and returns a verdict + prioritized issue list — it does NOT edit code.
+---
+
+You are a principal engineer doing a focused code review. You read the change and judge it. You do
+**not** modify code — you report. Keep the main thread's context clean: return conclusions, not a tour.
+
+## How to review
+1. Get the diff: `git diff` (unstaged) and `git diff --staged`, plus `git status`. If given specific
+   files/commits, scope to those (`git show <sha>`).
+2. Read the changed files and their immediate collaborators. Check against the relevant `AGENTS.md`
+   (root + the folder being changed; `CLAUDE.md` is just an `@AGENTS.md` shim) — convention violations are review findings.
+3. Judge on these axes, in priority order:
+   - **Correctness** — does it do what was intended? Logic bugs, races, off-by-one, wrong async/await.
+   - **Tests** — is there a test that would fail without this change? (TDD law.) Edge cases covered?
+   - **Security** — injection (parameterized queries?), authn/z, secret exposure, unvalidated input,
+     over-broad exception swallowing that hides failures.
+   - **Contracts** — backend response models ↔ frontend types alignment; API shape changes; **the path
+     a client calls actually reaches the server** (prefixes, proxies, base URLs).
+   - **Conventions** — per the project's `AGENTS.md` (typed boundaries, no absolute paths, no silent
+     failures/logging, layering, framework idioms).
+   - **Simplicity** — dead code, duplication, needless abstraction (YAGNI), clearer alternative.
+
+## Severity
+- **blocking** — must fix before merge (bug, security hole, missing test for behavior change, broken
+  client↔server contract, violation of a stated project law).
+- **should-fix** — real issue, fix now unless there's a reason.
+- **nit** — style/polish; optional.
+
+## Return format (always end with this)
+```
+review:
+  verdict: approved | changes-requested
+  blocking:
+    - file: <path:line>   issue: <what>   fix: <concrete suggestion>
+  should_fix:
+    - file: <path:line>   issue: <what>   fix: <suggestion>
+  nits:
+    - file: <path:line>   note: <what>
+  good: <one line on what's done well, if anything>
+```
+`verdict: approved` requires an empty `blocking` list. Be specific with `file:line`. Do not fix; report.
+
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`REVIEW: CLEAN` (empty `blocking` list) or `REVIEW: BLOCKING` (one or more blocking items). Automated
+runners read only this line, so it is mandatory and must exactly match one of those two forms.

package/bundles/antigravity-plugin/agents/preflight.md

@@ -0,0 +1,53 @@
+---
+name: preflight
+description: Use this agent to validate an implementation plan (or a phase of it) against the ACTUAL codebase before writing code. Use proactively right after a plan is drafted and before starting a phase. Checks that every technical claim in the plan — file paths, symbol names, API shapes, data fields, dependencies — matches reality. Read-only; returns a PASS/FAIL report. Does not fix anything.
+---
+
+You are a plan-validation specialist. Your job: catch the plan's wrong assumptions **before** they
+become wasted implementation. You diagnose; you do not fix and you do not write code.
+
+## What to validate (7 categories)
+For the plan (or the named phase) check each claim against the codebase:
+1. **File paths** — every file the plan says to create/edit: does the parent dir exist? Does an
+   existing file already cover it (collision/duplication)?
+2. **Symbols** — referenced functions/classes/components/hooks: do they exist with that exact name and
+   signature? (`grep` them.) Flag renamed/missing ones.
+3. **API shapes** — endpoints, request/response models: do the cited routes and types exist and match
+   the fields the plan assumes? Does the path a client will call actually reach the server (prefix/proxy)?
+4. **Data fields** — JSON paths / DB columns the plan binds to: do they exist in the models/fixtures?
+5. **Dependencies** — libraries/primitives the plan needs: declared in the manifest? installed? (e.g. a
+   UI primitive the plan assumes exists — confirm the component/package is actually present.)
+6. **Conventions** — does the plan's approach fit the patterns in the relevant `AGENTS.md`? Flag drift.
+7. **Test strategy** — does the plan put a failing test first for each behavior change (TDD law)?
+8. **Local-coder readiness** — could a low-capability model implement each phase with no reasoning of
+   its own? Flag any phase that leaves a judgment call open, names a file/symbol vaguely, omits exact
+   data bindings, or has a non-literal exit gate. (Supports the planner→coder handoff.)
+
+## Method
+- Read the plan. For each claim, run the cheapest check that confirms or refutes it (Glob/Grep/Read).
+- Don't trust the plan's prose — verify against files. A claim you can't verify is a finding, not a pass.
+
+## Return format (always end with this)
+```
+preflight:
+  verdict: PASS | FAIL
+  phase: <which phase/scope validated, or "whole plan">
+  findings:
+    - category: <paths|symbols|api|data|deps|conventions|tests|local-coder>
+      severity: blocker | warning
+      claim: <what the plan asserts>
+      reality: <what the codebase actually shows>
+      fix: <what the plan should say instead>
+  local_coder_ready: yes | no
+  local_coder_gaps:
+    - phase: <phase> — <what a weak coder would have to reason out / what's underspecified>
+  verified_ok:
+    - <short list of key claims that checked out>
+```
+`PASS` requires zero `blocker` findings. `local_coder_ready: no` lists the phases that lean on implied
+reasoning (a warning, not a hard blocker unless the plan targets a local coder). Be concrete: cite the
+file/symbol you checked.
+
+**Then, as the very last line of your output (nothing after it), emit the machine verdict:**
+`PREFLIGHT: PASS` (zero blocker findings) or `PREFLIGHT: FAIL` (one or more blockers). Automated runners
+read only this line, so it is mandatory and must exactly match one of those two forms.

package/bundles/antigravity-plugin/guard_agy.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""caddis `guard` hook for agy (Antigravity) — PreToolUse event.
+
+Ports claude-harness/hooks/guard.py to agy's contract: the risk CLASSIFIERS are copied in verbatim
+(same tiers, same regexes, same escape hatch); only the I/O envelope is rewritten. Self-contained
+(the agy bundle ships neither claude-harness/hooks/ nor scripts/), stdlib-only.
+
+agy PreToolUse stdin (camelCase protojson):
+  {"toolCall": {"name": "run_command", "args": {"CommandLine": "rm -rf /"}}, "stepIdx": N,
+   "conversationId": "…", "workspacePaths": ["…"], "transcriptPath": "…", "modelName": "…"}
+  NOTE: cwd is the PLUGIN dir, not the workspace — the repo root comes from workspacePaths[0].
+
+agy PreToolUse stdout (a decision object):
+  deny        -> {"decision": "deny",       "reason": "…"}   (hard block)
+  ask/confirm -> {"decision": "force_ask",  "reason": "…"}   (always prompt; defeats the allow-cache)
+  allow       -> nothing at all. Printing {"decision":"allow"} would *override* agy's own permission
+                 prompt for that call; staying silent falls through to normal handling, which is what
+                 the Claude Code guard does too.
+
+*** FAIL OPEN — the load-bearing property of this file ***
+agy may fail-closed on a hook error, so a bug here must degrade to "no guard" (agy's state today),
+never to a bricked agent. Every stage is wrapped: on ANY exception, malformed payload, unknown shape
+or encoding problem this prints NOTHING and exits 0. It never raises, never exits non-zero, and never
+emits a partial/malformed decision (the JSON is built and serialized before a single byte is printed).
+
+Write-tier gating (classify_write) is wired defensively: agy's file-edit tool name is still
+LIVE-CHECK-PENDING (see .caddis/plans/agy-hooks-port.md), so it applies only to a tool whose name
+looks like an edit/write and whose args carry a path. Unknown tools -> allow.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+# Functional identity, mirrored from scripts/claudster_config.py. Read order: the current dir first,
+# the pre-rename dir as a one-version fallback.
+_ARTIFACT_DIRS = (".caddis", ".claudster")
+_ENV_PREFIX = "CADDIS"
+_LEGACY_ENV_PREFIX = "CLAUDSTER"
+
+# ── protected-path rules (write → deny) ──────────────────────────────────────
+_SECRET_BASENAMES = {"id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "credentials",
+                     ".npmrc", ".pypirc", ".netrc", ".pgpass", ".htpasswd"}
+_SECRET_SUFFIXES = (".pem", ".key", ".p12", ".pfx", ".keystore", ".jks")
+_ENV_RE = re.compile(r"(^|/)\.env(\.|$)", re.I)
+_ENV_EXAMPLE_RE = re.compile(r"\.env\.(example|sample|template|dist)$", re.I)
+
+# Lockfiles are normally regenerated by the package manager, so a hand-edit is unusual enough to
+# confirm. Routine manifests (package.json/tsconfig) are deliberately NOT gated — too frequent, not risky.
+_ASK_BASENAMES = {"package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock", "cargo.lock",
+                  "uv.lock", "composer.lock", "gemfile.lock"}
+_CI_WORKFLOW_RE = re.compile(r"(^|/)(\.github|\.gitea)/workflows/", re.I)
+
+
+def classify_write(file_path: str) -> tuple[str, str]:
+    """Risk tier (deny|ask|allow) + reason for writing/editing ``file_path``."""
+    p = file_path.replace("\\", "/")
+    parts = [seg.lower() for seg in p.split("/") if seg]
+    base = parts[-1] if parts else ""
+
+    if any(seg in ("secrets", ".secrets") for seg in parts):
+        return "deny", f"writes into a secrets directory ({base})"
+    if ".git" in parts[:-1]:
+        return "deny", "writes into the .git internal directory"
+    if _ENV_RE.search(p) and not _ENV_EXAMPLE_RE.search(p):
+        return "deny", f"writes an environment/secret file ({base})"
+    if base in _SECRET_BASENAMES or any(base.endswith(s) for s in _SECRET_SUFFIXES):
+        return "deny", f"writes a credential/key file ({base})"
+
+    if base in _ASK_BASENAMES:
+        return "ask", f"edits a lockfile ({base})"
+    if _CI_WORKFLOW_RE.search(p):
+        return "ask", "edits a CI/CD workflow"
+    return "allow", ""
+
+
+# ── bash rules ───────────────────────────────────────────────────────────────
+# Catastrophic delete targets: a filesystem/home root or a *bare* drive root (C:\ ), NOT a drive
+# subpath (E:\proj\dist falls through to ask).
+_CATASTROPHIC_TARGET = re.compile(
+    r"--no-preserve-root"
+    r"|(?:^|\s)(?:/|/\*|~/|~|\$\{?HOME\}?)(?:\s|$|;|&|\|)"
+    r"|(?:^|\s)[A-Za-z]:[\\/]?(?:\s|$|;|&|\|)",
+    re.I,
+)
+_FORK_BOMB = re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:")
+
+
+def _strip_quotes(s: str) -> str:
+    """Drop quotes so quoted flags/targets still match (rm '-rf' \"/\" → rm -rf /)."""
+    return s.replace('"', "").replace("'", "")
+
+
+def _has_flag(cmd: str, letter: str, longname: str) -> bool:
+    """True if `cmd` carries the short flag (e.g. -rf / -r) or the long flag (--recursive)."""
+    return bool(re.search(rf"(?:^|\s)-\w*{letter}\w*\b", cmd, re.I)) or longname in cmd.lower()
+
+
+def _is_rm_recursive_force(cmd: str) -> bool:
+    if not re.search(r"\brm\b", cmd):
+        return False
+    return _has_flag(cmd, "r", "--recursive") and _has_flag(cmd, "f", "--force")
+
+
+def _is_win_recursive_delete(cmd: str) -> bool:
+    """Native Windows recursive delete — the POSIX ``rm`` path is handled by _is_rm_recursive_force.
+
+    Catches PowerShell ``Remove-Item -Recurse -Force`` (and the Remove-Item aliases ri/rmdir/rd/del/
+    erase) plus cmd.exe ``rmdir``/``rd``/``del``/``erase`` with the ``/s`` recurse-subdirectories switch.
+    This is a Windows-primary environment, so these are the real footguns the POSIX rules miss."""
+    if not re.search(r"(?:^|[\s;&|(])(?:remove-item|ri|rmdir|rd|del|erase)\b", cmd, re.I):
+        return False
+    ps_recurse_force = bool(re.search(r"(?:^|\s)-rec\w*", cmd, re.I)) and bool(re.search(r"(?:^|\s)-for\w*", cmd, re.I))
+    cmd_slash_s = bool(re.search(r"(?:^|\s)/s\b", cmd, re.I))
+    return ps_recurse_force or cmd_slash_s
+
+
+def classify_bash(command: str) -> tuple[str, str]:
+    """Risk tier (deny|ask|allow) + reason for a shell command."""
+    c = command.strip()
+    cl = c.lower()
+    n = _strip_quotes(c)          # quote-normalized: defeats `rm '-rf' "/"` evasion
+    nl = n.lower()
+    rm_rf = _is_rm_recursive_force(n)
+    catastrophic = bool(_CATASTROPHIC_TARGET.search(n))
+    find_delete = bool(re.search(r"\bfind\b.*?(?:-delete\b|-exec\s+rm\b)", nl))
+    win_del = _is_win_recursive_delete(n)
+
+    # ── deny: catastrophic ──
+    if rm_rf and catastrophic:
+        return "deny", "recursive force-delete of a root/home path (rm -rf)"
+    if find_delete and catastrophic:
+        return "deny", "find -delete from a root/home path"
+    if win_del and catastrophic:
+        return "deny", "recursive force-delete of a root/home path (Windows Remove-Item/rmdir)"
+    if re.search(r"\brmtree\s*\(\s*['\"]?(?:/|~|[A-Za-z]:\\?)['\"]?\s*\)", c, re.I):
+        return "deny", "recursive tree delete of a root/home path (rmtree)"
+    if _FORK_BOMB.search(c):
+        return "deny", "fork bomb"
+    if re.search(r"\bdd\b.*\bof=/dev/", nl) or re.search(r"\bmkfs", nl) or re.search(r">\s*/dev/sd[a-z]", nl):
+        return "deny", "writes directly to a disk device"
+    if (re.search(r"\bchmod\b", nl) and _has_flag(n, "r", "--recursive")
+            and re.search(r"\b0?777\b", nl) and catastrophic):
+        return "deny", "recursive chmod 777 on a root path"
+
+    # ── ask: destructive-but-legit ──
+    if rm_rf:
+        return "ask", "recursive force-delete (rm -rf)"
+    if find_delete:
+        return "ask", "find with -delete / -exec rm"
+    if win_del:
+        return "ask", "recursive delete (Windows Remove-Item -Recurse / rmdir /s)"
+    # git rules tolerate intervening options (e.g. `git -c k=v push --force`) but stay within one
+    # command segment (the [^;&|]* won't cross a ; && || into an unrelated command). The trailing
+    # `+\S` catches a force-push via refspec (`git push origin +main`), not just the --force flags.
+    if re.search(r"\bgit\b[^;&|]*\bpush\b[^;&|]*(--force\b|--force-with-lease\b|(?:^|\s)-f\b|(?:^|\s)\+\S)", c):
+        return "ask", "git force-push"
+    if re.search(r"\bgit\b[^;&|]*\breset\s+--hard\b", c):
+        return "ask", "git reset --hard"
+    if re.search(r"\bgit\b[^;&|]*\bclean\b[^;&|]*(?:^|\s)-\w*f", c):
+        return "ask", "git clean (force)"
+    if re.search(r"\bgit\b[^;&|]*\bfilter-(repo|branch)\b", c):
+        return "ask", "git history rewrite"
+    if re.search(r"\b(drop\s+(table|database|schema)|truncate\s+table)\b", cl):
+        return "ask", "destructive SQL (drop/truncate)"
+    if re.search(r"\b(npm|yarn|pnpm)\s+publish\b|\btwine\s+upload\b|\bcargo\s+publish\b", cl):
+        return "ask", "publishing a package"
+    if re.search(r"\b(curl|wget|iwr|invoke-webrequest)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|iex|python)\b", cl):
+        return "ask", "piping a download into a shell"
+    return "allow", ""
+
+
+# ── agy tool-shape mapping ───────────────────────────────────────────────────
+# The shell tool: step type CORTEX_STEP_TYPE_RUN_COMMAND -> "run_command". The command lives at
+# args.CommandLine. Extra spellings are accepted so a step-type rename can't silently un-guard the
+# shell (a missed tool name = no guard at all, which is the failure we most want to avoid).
+_COMMAND_TOOLS = {"run_command", "runcommand", "run_terminal_command", "bash", "shell", "terminal"}
+_COMMAND_ARG_KEYS = ("CommandLine", "commandLine", "command_line", "command", "Command")
+
+# Write-ish tool detection is heuristic until the live check pins agy's file-edit tool name.
+_WRITE_NAME_RE = re.compile(r"(edit|write|create|replace|patch|append)", re.I)
+_READONLY_NAME_RE = re.compile(r"(view|read|list|search|grep|find|browser|open)", re.I)
+_PATH_ARG_KEYS = ("FilePath", "filePath", "file_path", "AbsolutePath", "absolutePath",
+                  "TargetFile", "targetFile", "Path", "path")
+
+
+def _first_str(args: dict, keys) -> str:
+    for k in keys:
+        v = args.get(k)
+        if isinstance(v, str) and v.strip():
+            return v
+    return ""
+
+
+def decide(tool_name: str, args, allow_patterns: list[str]) -> tuple[str, str]:
+    """Top-level decision. Classify FIRST; the allow escape hatch may only DOWNGRADE an `ask` to
+    `allow` (never override a `deny`), and it matches the command/path value — not the JSON envelope —
+    so a key name like "command" can't disable the guard. Never raises on a malformed payload."""
+    if not isinstance(args, dict):
+        return "allow", ""
+    name = (tool_name or "").strip().lower()
+
+    if name in _COMMAND_TOOLS:
+        target = _first_str(args, _COMMAND_ARG_KEYS)
+        tier, reason = classify_bash(target) if target else ("allow", "")
+    elif _WRITE_NAME_RE.search(name) and not _READONLY_NAME_RE.search(name):
+        target = _first_str(args, _PATH_ARG_KEYS)
+        tier, reason = classify_write(target) if target else ("allow", "")
+    else:
+        return "allow", ""
+
+    if tier == "ask" and any(pat and pat.lower() in target.lower() for pat in allow_patterns):
+        return "allow", ""
+    return tier, reason
+
+
+# ── config (per-repo escape hatch + kill switch) ─────────────────────────────
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _config_path(root: str) -> str | None:
+    """The repo's ``config.toml`` — ``.caddis`` preferred, legacy ``.claudster`` as fallback."""
+    for name in _ARTIFACT_DIRS:
+        cfg = os.path.join(str(root), name, "config.toml")
+        if os.path.isfile(cfg):
+            return cfg
+    return None
+
+
+def _load_guard_config(root: str) -> dict:
+    """Parse the ``[guard]`` table from the repo's ``config.toml``; {} on any problem."""
+    cfg = _config_path(root)
+    if cfg is None:
+        return {}
+    try:
+        import tomllib
+        with open(cfg, "rb") as fh:
+            data = tomllib.load(fh)
+        section = data.get("guard", {})
+        return section if isinstance(section, dict) else {}
+    except Exception:
+        return {}
+
+
+def _load_allow(root: str) -> list[str]:
+    allow = _load_guard_config(root).get("allow", [])
+    return [str(x) for x in allow] if isinstance(allow, list) else []
+
+
+def guard_disabled(root: str) -> bool:
+    """True when the guard is turned off entirely (all tiers bypassed).
+
+    Precedence: the env var wins (global); otherwise the per-repo `[guard]` table — `enabled = false`
+    or `mode = "off"`. Any parse problem → not disabled (fail safe). CADDIS_GUARD_DISABLED is the
+    current name; the pre-rename CLAUDSTER_GUARD_DISABLED is read only when the new name is unset."""
+    _disabled = os.environ.get(f"{_ENV_PREFIX}_GUARD_DISABLED")
+    if _disabled is None:
+        _disabled = os.environ.get(f"{_LEGACY_ENV_PREFIX}_GUARD_DISABLED", "")
+    if _disabled.strip().lower() in _TRUTHY:
+        return True
+    section = _load_guard_config(root)
+    if section.get("enabled") is False:
+        return True
+    if str(section.get("mode", "")).strip().lower() == "off":
+        return True
+    return False
+
+
+def deny_only(root: str) -> bool:
+    """True when the guard keeps DENY (silent hard-block) but suppresses the ASK tier (ask -> allow =
+    silence), so it NEVER prompts — for autonomous / no-prompt workflows that still want a catastrophe
+    net. Env `CADDIS_GUARD_MODE=deny-only` (`CLAUDSTER_GUARD_MODE` fallback); config `[guard] mode =
+    "deny-only"`. Read silently."""
+    _mode = os.environ.get(f"{_ENV_PREFIX}_GUARD_MODE")
+    if _mode is None:
+        _mode = os.environ.get(f"{_LEGACY_ENV_PREFIX}_GUARD_MODE", "")
+    if _mode.strip().lower() == "deny-only":
+        return True
+    section = _load_guard_config(root)
+    return str(section.get("mode", "")).strip().lower() == "deny-only"
+
+
+# ── hook I/O glue (agy envelope) ─────────────────────────────────────────────
+_AGY_DECISION = {"deny": "deny", "ask": "force_ask"}
+
+
+def _emit(tier: str, reason: str) -> None:
+    """Serialize the decision FIRST, then print once — a failure mid-build can never leave agy
+    reading half an object. Silence (allow) is the default for anything that isn't deny/ask."""
+    decision = _AGY_DECISION.get(tier)
+    if not decision:
+        return
+    tail = (" Blocked as too dangerous to run automatically — do it by hand if you are certain."
+            if tier == "deny" else " Confirm only if this is intended.")
+    payload = json.dumps({"decision": decision, "reason": f"[caddis guard] {reason}.{tail}"})
+    sys.stdout.write(payload)
+
+
+def main() -> None:
+    tier, reason = "allow", ""
+    try:
+        _reconfig = getattr(sys.stdout, "reconfigure", None)
+        if _reconfig:
+            try:
+                _reconfig(encoding="utf-8")
+            except Exception:
+                pass
+        try:
+            data = json.load(sys.stdin)
+        except Exception:
+            return  # malformed payload → fail open, silently
+        if not isinstance(data, dict):
+            return
+        call = data.get("toolCall")
+        if not isinstance(call, dict):
+            return
+        workspaces = data.get("workspacePaths") or []
+        root = workspaces[0] if isinstance(workspaces, list) and workspaces else os.getcwd()
+        if guard_disabled(str(root)):
+            return  # kill switch: bypass every tier
+        tier, reason = decide(str(call.get("name") or ""), call.get("args"), _load_allow(str(root)))
+        if tier == "ask" and deny_only(str(root)):
+            tier = "allow"  # deny-only: keep catastrophe blocks, never force_ask (no plan interruption)
+    except Exception:
+        return  # ANY unexpected shape/error → no guard, never a crash and never a bad decision
+    finally:
+        try:
+            _emit(tier, reason)
+        except Exception:
+            pass
+        # Always exit 0: a non-zero code from a PreToolUse hook is an agy hook *error*.
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/bundles/antigravity-plugin/hooks.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python guard_agy.py",
+            "windows": "python guard_agy.py",
+            "linux": "python3 guard_agy.py",
+            "osx": "python3 guard_agy.py"
+          }
+        ]
+      }
+    ],
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "python warm_start_agy.py",
+        "windows": "python warm_start_agy.py",
+        "linux": "python3 warm_start_agy.py",
+        "osx": "python3 warm_start_agy.py"
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "python session_end_agy.py",
+        "windows": "python session_end_agy.py",
+        "linux": "python3 session_end_agy.py",
+        "osx": "python3 session_end_agy.py"
+      }
+    ]
+  }
+}

package/bundles/antigravity-plugin/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "caddis": {
+      "command": "python",
+      "args": ["mcp_ping_server.py"]
+    }
+  }
+}