@caddis/cli 0.4.56 → 0.4.57

package/bundles/antigravity-plugin/guard_agy.py

@@ -17,11 +17,19 @@ agy PreToolUse stdout (a decision object):
                  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).
+*** NEVER A HOOK ERROR — the load-bearing property of this file ***
+agy may fail-closed on a hook error, so this hook 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). Within that:
+  * a payload it cannot read (not JSON, no toolCall, wrong shapes) prints NOTHING: there is no call to judge;
+  * an internal error while judging a shell or write call prints a well-formed DENY ("guard error: ..."),
+    as guard.py does (robustness #13). A deny is a decision, not a hook error, so it blocks one call and
+    never bricks the agent. Any other tool stays open. agy has no `onFailure` hook field (checked in the
+    binary, 19 Oct), so this deny, plus `timeout: 30` in hooks.json, is the whole fail-closed story here.
+
+Kill switch (robustness #13), as guard.py: only env CADDIS_GUARD_DISABLED=1 turns the guard fully off, and
+only interactively; under CADDIS_HEADLESS=1 it acts as deny-only. `[guard] enabled = false` / `mode = "off"`
+in `.caddis/config.toml` acts as deny-only. A write to `.caddis/config.toml` or `~/.caddis/*.toml` asks.
+The spawn-session tree lock is ported from guard.py too.
 
 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
@@ -30,10 +38,13 @@ looks like an edit/write and whose args carry a path. Unknown tools -> allow.
 from __future__ import annotations
 
 import json
+import math
 import os
 import re
 import shlex
+import subprocess
 import sys
+import time
 
 # Functional identity, mirrored from scripts/claudster_config.py.
 _ARTIFACT_DIR = ".caddis"
@@ -44,7 +55,7 @@ _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)
+_ENV_EXAMPLE_RE = re.compile(r"\.env(\.[\w-]+)*\.(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.
@@ -55,7 +66,7 @@ _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("\\", "/")
+    p = file_path.replace("\\", "/").rstrip(". ")  # Windows drops a trailing dot or space: `.env.` is `.env`
     parts = [seg.lower() for seg in p.split("/") if seg]
     base = parts[-1] if parts else ""
 
@@ -68,6 +79,9 @@ def classify_write(file_path: str) -> tuple[str, str]:
     if base in _SECRET_BASENAMES or any(base.endswith(s) for s in _SECRET_SUFFIXES):
         return "deny", f"writes a credential/key file ({base})"
 
+    why = guard_config_reason(file_path)
+    if why:
+        return "ask", why
     if base in _ASK_BASENAMES:
         return "ask", f"edits a lockfile ({base})"
     if _CI_WORKFLOW_RE.search(p):
@@ -75,6 +89,68 @@ def classify_write(file_path: str) -> tuple[str, str]:
     return "allow", ""
 
 
+# ── the guard's own config (robustness #13) — copied from hooks/guard.py ─────
+_WHY_CONFIG = "edits caddis config ({}); a guard setting there can relax the guard, so confirm the change is yours"
+
+
+# The home folder as a shell spells it: PowerShell `$env:USERPROFILE` / `$env:HOME` / `$HOME`, bash `$HOME` /
+# `${HOME}` / `$USERPROFILE` / `${USERPROFILE}`, cmd `%USERPROFILE%` / `%HOME%`; `~user` is out of scope. Each
+# becomes `~`, which _home_path expands from os.path.expanduser("~") (os.path.expandvars knows neither `$env:` nor
+# an unset HOME on Windows).
+_HOME_VAR = re.compile(r"\$\{?env:(?:userprofile|home)\}?|\$\{(?:home|userprofile)\}|\$(?:home|userprofile)\b"
+                       r"|%(?:userprofile|home)%", re.I)
+
+
+def _home_path(raw: str) -> str:
+    """``raw`` with a leading home spelling (`~`, `$HOME`, `$env:USERPROFILE`, `%USERPROFILE%`) made absolute."""
+    raw = _HOME_VAR.sub("~", raw)
+    if raw == "~" or raw[:2] in ("~/", "~\\"):
+        raw = os.path.expanduser("~") + raw[1:]
+    return raw
+
+
+def guard_config_reason(path: str) -> str:
+    """The ask reason when ``path`` is a `.caddis/config.toml` or a `~/.caddis/*.toml`, else ''."""
+    if not isinstance(path, str):
+        return ""
+    raw = path.strip().strip("'\"")
+    parts = [seg.lower() for seg in raw.replace("\\", "/").rstrip(". ").split("/") if seg]
+    if not parts or not parts[-1].endswith(".toml"):
+        return ""
+    if len(parts) >= 2 and parts[-2] == _ARTIFACT_DIR and parts[-1] == "config.toml":
+        return _WHY_CONFIG.format(parts[-1])
+    full = os.path.abspath(os.path.normpath(_home_path(raw).replace("\\", "/")))
+    home = os.path.join(os.path.expanduser("~"), _ARTIFACT_DIR)
+    if os.path.normcase(os.path.realpath(os.path.dirname(full))) == os.path.normcase(os.path.realpath(home)):
+        return _WHY_CONFIG.format(f"~/{_ARTIFACT_DIR}/{parts[-1]}")
+    return ""
+
+
+# Copied from hooks/guard.py: the Read rule, used by the shell secret-read rule below.
+def classify_read(file_path: str) -> tuple[str, str]:
+    """Risk tier (deny|allow) + reason for reading ``file_path`` via the Read tool.
+
+    Mirrors classify_write's env, credential, and secrets-directory rules, minus .git internals
+    and the lockfile/CI `ask` tier. Reading .git internals is normal. Never
+    returns "ask": Read is either fine or a secret disclosure, there's no confirm-and-proceed tier
+    for a read that already happened by the time the user could answer.
+
+    ``.envrc`` (direnv) is NOT ``.env``: _ENV_RE requires the char right after ".env" to be "." or
+    end-of-segment, and "rc" is neither, so `.envrc` falls through to allow — intentional, direnv
+    files are config, not the secret-bearing `.env`/`.env.*` family."""
+    p = file_path.replace("\\", "/").rstrip(". ")
+    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[:-1]):
+        return "deny", f"reads from a secrets directory ({base})"
+    if _ENV_RE.search(p) and not _ENV_EXAMPLE_RE.search(p):
+        return "deny", "reads a secret env file"
+    if base in _SECRET_BASENAMES or any(base.endswith(s) for s in _SECRET_SUFFIXES):
+        return "deny", f"reads a credential/key file ({base})"
+    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).
@@ -387,6 +463,118 @@ def git_add_everything(command: str, depth: int = 0) -> bool:
                for _cwd, sub, args in _git_calls(command, None, depth))
 
 
+# Copied from hooks/guard.py (robustness #13): shell writes onto the guard's config.
+# Shell constructs that WRITE to a named target: redirections, and the usual suspects that take
+# a path argument. Matching the target lets classify_write judge it, so the shell path and the
+# Write/Edit path can never disagree about what counts as a secret.
+_SHELL_WRITE_TARGET = re.compile(
+    r"""(?:
+          >>?\s*(?P<redir>[^\s|;&<>]+)                      # > file   >> file
+        | \|\s*tee\s+(?:-a\s+)?(?P<tee>[^\s|;&<>]+)          # | tee file
+        | -(?:Path|FilePath|LiteralPath)\s+(?P<ps>[^\s|;&]+) # Set-Content -Path file
+        | \bOut-File\s+(?P<outfile>[^\s|;&]+)                # Out-File file
+    )""",
+    re.IGNORECASE | re.VERBOSE,
+)
+
+
+def _shell_write_targets(command: str) -> list[str]:
+    """Every path this command appears to write to, quotes removed: a redirection, `| tee`, `| Out-File`, and the
+    targets of the writer programs the config rule knows (cp, mv, Copy-Item, Set-Content, New-Item, Tee-Object, sed -i,
+    ...). Not the regex's `-Path` group: `Get-Content -Path x` reads. Best-effort by design: a miss degrades to the old
+    behaviour, it never invents a denial. guard_agy.py carries a copy; test_guard_agy.py checks they agree."""
+    command = _HOME_VAR.sub("~", command)  # the tokenizer splits on `$`, so in `$HOME/x` the home part would be lost
+    out = [m.group(g).strip("'\"") for m in _SHELL_WRITE_TARGET.finditer(command)
+           for g in ("redir", "tee", "outfile") if m.group(g)]
+    try:
+        for name, _cwd, _sub, args in _tool_calls(command, None, _CONFIG_WRITERS):
+            if name == "sed":
+                if any(a.startswith(("-i", "--in-place")) for a in args):
+                    out += [a for a in args if not a.startswith("-")]
+            elif name == "tee":
+                out += [a for a in args if not a.startswith(("-", "<", ">"))]
+            elif name in _CONFIG_SETTERS:
+                out += _setter_targets(args)
+            else:
+                out += _copier_targets(args)
+    except Exception:  # noqa: BLE001 - a tokenizer failure keeps the regex targets; it never switches the rule off
+        pass
+    return out
+
+
+# Shell writes onto the guard's config: redirections and `| tee` / `| Out-File` (the regex above, not its -Path
+# group: Get-Content -Path reads), then the programs below, found with the tokenizer (wrapped shells and `cd` count).
+# Known limits: an interpreter one-liner (`python -c "open(...,'w')"`), a script that writes the file, a variable
+# other than the home folder (_HOME_VAR), a symlink or glob that points at the file.
+_CONFIG_COPIERS = frozenset({"cp", "copy", "mv", "move", "copy-item", "move-item", "cpi", "mi", "install"})
+_CONFIG_SETTERS = frozenset({"set-content", "sc", "add-content", "ac", "out-file", "new-item", "ni", "tee-object"})
+_CONFIG_WRITERS = _CONFIG_COPIERS | _CONFIG_SETTERS | {"tee", "sed"}
+_PS_PATH_PARAMS = {"-path", "-literalpath", "-filepath", "-pspath"}
+_PS_VALUE_PARAMS = {"-value", "-encoding", "-inputobject", "-width", "-stream", "-delimiter", "-itemtype",
+                    "-filter", "-include", "-exclude", "-credential", "-variable"}
+
+
+def _setter_targets(args: list[str]) -> list[str]:
+    """Set-Content / Out-File / New-Item: the -Path value, else the first positional word (+ New-Item -Name)."""
+    path, name, positional, i = "", "", [], 0
+    while i < len(args):
+        word = args[i].lower()
+        if word in _PS_PATH_PARAMS and i + 1 < len(args):
+            path, i = args[i + 1], i + 2
+        elif word == "-name" and i + 1 < len(args):
+            name, i = args[i + 1], i + 2
+        elif word in _PS_VALUE_PARAMS:
+            i += 2
+        else:
+            if not word.startswith(("-", ">", "<")):
+                positional.append(args[i])
+            i += 1
+    path = path or (positional[0] if positional else "")
+    return [os.path.join(path or ".", name) if name else path] if (path or name) else []
+
+
+def _copier_targets(args: list[str]) -> list[str]:
+    """cp / mv / Copy-Item / Move-Item: the destination, and destination/<source name> for a folder destination."""
+    sources, dest, i = [], "", 0
+    while i < len(args):
+        word = args[i].lower()
+        if word in ("-destination", "-t", "--target-directory") and i + 1 < len(args):
+            dest, i = args[i + 1], i + 2
+            continue
+        if word.startswith("--target-directory="):
+            dest = args[i].split("=", 1)[1]
+        elif word in ("-path", "-literalpath") and i + 1 < len(args):
+            sources.append(args[i + 1])
+            i += 1
+        elif not word.startswith(("-", ">", "<")):
+            sources.append(args[i])
+        i += 1
+    if not dest and len(sources) >= 2:
+        dest = sources.pop()
+    if not dest:
+        return []
+    return [dest] + [os.path.join(dest, os.path.basename(src.replace("\\", "/"))) for src in sources]
+
+
+def guard_config_shell_reason(command: str) -> str:
+    """The ask reason when a shell command writes a `.caddis/config.toml` or `~/.caddis/*.toml`, else ''.
+    Callers pass heredoc-free text and treat an exception as "no match"."""
+    targets = _shell_write_targets(command)
+    for target in targets:
+        why = guard_config_reason(target)
+        if why:
+            return f"shell command {why}"
+    return ""
+
+
+def _config_shell_safe(text: str) -> str:
+    """guard_config_shell_reason, but an error is "no match": one rule must never switch off the rest."""
+    try:
+        return guard_config_shell_reason(text)
+    except Exception:  # noqa: BLE001 - fail open for this rule only; the other rules still run
+        return ""
+
+
 # Copied from hooks/guard.py: a heredoc body that only carries data is not a command.
 _HEREDOC_MARKER = re.compile(
     r"<<(-?)[ \t]*(?:'([A-Za-z_][A-Za-z_0-9]*)'|\"([A-Za-z_][A-Za-z_0-9]*)\"|([A-Za-z_][A-Za-z_0-9]*))"
@@ -480,11 +668,15 @@ _NPM_VALUE_FLAGS = {"--registry", "--userconfig", "--prefix", "-w", "--workspace
                     "--cache", "-C", "--cwd", "--dir"}
 
 
+def _headless() -> bool:
+    """A headless session: CADDIS_HEADLESS set, not empty, not 0. The hook reads the marker from its own
+    environment: Claude Code and agy start hooks with the session's env, which the model's shell cannot change."""
+    return str(os.environ.get(f"{_ENV_PREFIX}_HEADLESS", "")).strip() not in ("", "0")
+
+
 def _publish_allowed_headless() -> bool:
-    """False only in a headless session (CADDIS_HEADLESS set, not empty, not 0) without CADDIS_ALLOW_PUBLISH=1.
-    The hook reads the marker from its own environment: Claude Code and agy start hooks with the session's env."""
-    headless = str(os.environ.get(f"{_ENV_PREFIX}_HEADLESS", "")).strip()
-    if headless in ("", "0"):
+    """False only in a headless session without CADDIS_ALLOW_PUBLISH=1."""
+    if not _headless():
         return True
     return str(os.environ.get(f"{_ENV_PREFIX}_ALLOW_PUBLISH", "")).strip() == "1"
 
@@ -586,6 +778,193 @@ def _headless_publish_safe(text: str) -> str:
         return ""
 
 
+# ── no tree moves in a shared checkout (robustness #11) ──
+# A checkout whose AGENTS.md says `Shared checkout: yes` has a dev service serving from it, and often a peer's
+# uncommitted edits. `git switch`, `checkout <branch>`, `rebase`, `pull`, `merge`, `reset --hard` and `stash` move
+# or discard its files. Interactive: ask. Headless (CADDIS_HEADLESS=1): deny, because deny-only mode turns every ask
+# into a silent allow and a runner session has no one to ask. `restore`/`checkout` of `.` or a folder discard a
+# peer's edits too; `reset --keep`/`--merge` count as `--hard`; `stash apply`/`pop` count. Free: `switch -c <new>` and
+# `checkout -b <new>` with NO start point (a start point checks that commit out), `checkout [-- ] <file>`,
+# `git worktree add`, `pull --dry-run`, and the recovery verbs (`rebase`/`merge` `--abort`/`--continue`/`--skip`/
+# `--quit`), so a headless runner can always finish or undo a stopped operation. `checkout <name>` where <name> is
+# both a path and a ref is a branch switch (one `git rev-parse`, run only then). The checkout is the one the command acts on (`cd`, `git -C`, as for staging). A
+# linked worktree is never shared: AGENTS.md is tracked, so the worktree has the line too, but it is the safe place.
+# Known limits (it catches accidents, it is not a boundary): a cwd from a variable (`cd $X`) is not followed, and a
+# git alias is not read. The regex is the one in scripts/caddis_checkout_guard.py (SHARED_RE); guard_agy.py carries
+# a copy, and test_guard_agy.py checks they agree.
+_SHARED_RE = re.compile(r"^[ \t]*(?:[-*][ \t]+)?(?:\*\*)?Shared checkout:[ \t]*yes(?:\*\*)?[ \t]*(?:$|[(\-–—.:,;#])",
+                        re.IGNORECASE | re.MULTILINE)
+_SWITCH_CREATE = {"-c", "-C", "--create", "--force-create"}
+_CHECKOUT_CREATE = {"-b", "-B", "--orphan"}
+_GIT_RECOVERY = {"--abort", "--continue", "--skip", "--quit"}  # a stopped rebase/merge must be finishable headless
+_RESET_MOVES = {"--hard", "--keep", "--merge"}
+_FORCE = {"-f", "--force", "--discard-changes"}  # `switch -f -c x` / `checkout -f -b x` throw changes away
+
+
+def _options(args: list[str]) -> list[str]:
+    """The words before `--`. After `--` every word is a pathspec, even `-b` or `--staged`."""
+    return args[:args.index("--")] if "--" in args else args
+
+
+def _create_flag(word: str, creates: set[str]) -> bool:
+    """`word` makes a branch: `-c`, attached `-cfoo`, or `--create=foo`."""
+    return word in creates or any(word.startswith(c + "=") if c.startswith("--") else
+                                  (word.startswith(c) and len(word) > len(c)) for c in creates)
+
+
+def _create_moves(args: list[str], creates: set[str]) -> bool:
+    """`switch -c <new> [<start>]` / `checkout -b <new> [<start>]`: True when a start point follows the new name, or
+    `-f`/`--force`/`--discard-changes` throws the tree's changes away. The bare form starts from HEAD and keeps
+    the tree; a start point checks that commit out."""
+    opts = _options(args)
+    if any(a in _FORCE for a in opts):
+        return True
+    named, skip = [], False
+    for a in opts:
+        if skip:
+            skip = False
+        elif a in creates:
+            skip = True  # the next word is the new branch name (`-cfoo` / `--create=foo` carry it)
+        elif not a.startswith("-"):
+            named.append(a)
+    return bool(named)
+
+
+def _broad_path(path: str, cwd: str) -> bool:
+    """A pathspec that can hold files other than the one named: `.`, a folder, a glob or pathspec magic (`:/`)."""
+    if path.startswith(":") or any(c in path for c in "*?["):
+        return True
+    return os.path.isdir(os.path.join(cwd, path))
+
+
+# No console window for the git call (a hook in a console-less session would flash one).
+_NO_WINDOW_KW = {"creationflags": 0x08000000} if os.name == "nt" else {}
+
+
+def _is_ref(name: str, cwd: str) -> bool:
+    """True when `name` resolves as a commit in the repo at `cwd`. Git cannot run (missing, hung): True, so the
+    caller asks. Called only when `name` is also a path, so most checkouts never pay for the git call."""
+    try:
+        r = subprocess.run(["git", "-C", cwd, "rev-parse", "--verify", "--quiet", f"{name}^{{commit}}"],
+                           capture_output=True, text=True, timeout=5, stdin=subprocess.DEVNULL,
+                           **_NO_WINDOW_KW)
+    except (OSError, subprocess.SubprocessError):
+        return True
+    return r.returncode == 0
+
+
+def _from_file(opts: list[str]) -> bool:
+    """`--pathspec-from-file`: the paths are in a file the guard does not read, so assume they are broad."""
+    return any(a == "--pathspec-from-file" or a.startswith("--pathspec-from-file=") for a in opts)
+
+
+def _checkout_moves(args: list[str], cwd: str) -> bool:
+    opts = _options(args)
+    if _from_file(opts):
+        return True
+    if any(_create_flag(a, _CHECKOUT_CREATE) for a in opts):
+        paths = args[len(opts) + 1:]
+        return _create_moves(args, _CHECKOUT_CREATE) or any(_broad_path(p, cwd) for p in paths)
+    if "--" in args:  # `checkout [<tree-ish>] -- <paths>`: only a broad pathspec discards more than the named file
+        paths = args[args.index("--") + 1:]
+        return not paths or any(_broad_path(p, cwd) for p in paths)
+    named = [a for a in args if not a.startswith("-")]
+    if not named or not all(os.path.exists(os.path.join(cwd, a)) for a in named):
+        return True  # `checkout <branch>`, `checkout -`
+    if _is_ref(named[0], cwd):  # a branch and a path share the name: git takes the branch
+        return len(named) == 1 or any(_broad_path(p, cwd) for p in named[1:])
+    return any(_broad_path(p, cwd) for p in named)
+
+
+def _restore_moves(args: list[str], cwd: str) -> bool:
+    opts = _options(args)
+    staged = any(a in ("-S", "--staged") for a in opts)
+    if staged and not any(a in ("-W", "--worktree") for a in opts):
+        return False  # `restore --staged` changes the index only
+    if _from_file(opts):
+        return True
+    paths, skip = list(args[len(opts) + 1:]), False
+    for a in opts:
+        if skip:
+            skip = False
+        elif a in ("-s", "--source"):
+            skip = True
+        elif not a.startswith("-"):
+            paths.append(a)
+    return any(_broad_path(p, cwd) for p in paths)
+
+
+def _moves_tree(sub: str, args: list[str], cwd: str) -> bool:
+    """True when `git <sub> <args>` moves or discards the work tree (see the block note)."""
+    verb = sub.lower()
+    if verb == "switch":
+        if any(_create_flag(a, _SWITCH_CREATE) for a in _options(args)):
+            return _create_moves(args, _SWITCH_CREATE)
+        return True
+    if verb == "checkout":
+        return _checkout_moves(args, cwd)
+    if verb == "restore":
+        return _restore_moves(args, cwd)
+    if verb in ("rebase", "merge"):
+        return not any(a in _GIT_RECOVERY for a in args)
+    if verb == "pull":
+        return "--dry-run" not in args
+    if verb == "reset":
+        return any(a in _RESET_MOVES for a in args)
+    if verb == "stash":
+        return not (args[:1] and args[0].lower() in ("list", "show"))
+    return False
+
+
+def _declares_shared(cwd: str) -> bool:
+    """The repo that holds `cwd` says `Shared checkout: yes` in its top AGENTS.md, and is not a linked worktree."""
+    here = os.path.abspath(cwd)
+    top = here
+    while True:
+        if os.path.exists(os.path.join(top, ".git")):
+            break
+        parent = os.path.dirname(top)
+        if parent == top:
+            top = here
+            break
+        top = parent
+    gitfile = os.path.join(top, ".git")
+    if os.path.isfile(gitfile):
+        try:
+            with open(gitfile, encoding="utf-8", errors="replace") as fh:
+                line = fh.read().strip()
+        except OSError:
+            line = ""
+        if line.lower().startswith("gitdir:") and "/worktrees/" in line.replace("\\", "/").lower():
+            return False
+    try:
+        with open(os.path.join(top, "AGENTS.md"), encoding="utf-8", errors="replace") as fh:
+            return bool(_SHARED_RE.search(fh.read()))
+    except OSError:
+        return False
+
+
+def shared_checkout_reason(command: str, root: str | None) -> str:
+    """The reason when `command` moves the tree of a checkout that says `Shared checkout: yes`, else ''.
+    Callers pass heredoc-free text and treat an exception as "no match"."""
+    for cwd, sub, args in _git_calls(command, root):
+        if cwd is None or "$" in cwd or "%" in cwd or not os.path.isdir(cwd):
+            continue
+        if _moves_tree(sub, args, cwd) and _declares_shared(cwd):
+            return (f"`git {sub.lower()}` moves the tree of a shared checkout (AGENTS.md says Shared checkout: yes; "
+                    "a dev service or a peer uses it). Work in your own worktree instead: "
+                    "`git worktree add \"$TEMP/<name>\" -b <branch> origin/<default>`, and remove it when done")
+    return ""
+
+
+def _shared_checkout_safe(text: str, root: str | None) -> str:
+    """shared_checkout_reason, but an error is "no match": one rule must never switch off the rest of the guard."""
+    try:
+        return shared_checkout_reason(text, root)
+    except Exception:  # noqa: BLE001 - fail open for this rule only; the other rules still run
+        return ""
+
+
 def _strip_quotes(s: str) -> str:
     """Drop quotes so quoted flags/targets still match (rm '-rf' \"/\" → rm -rf /)."""
     return s.replace('"', "").replace("'", "")
@@ -670,13 +1049,145 @@ def _catastrophic_statement(c: str) -> str:
     return ""
 
 
+# Copied from hooks/guard.py; test_guard_agy.py checks they agree.
+# ── Phase 6: reading or copying onto a secret env file through the shell ─────
+# Match copy/move verbs as whole tokens. Source and destination paths are checked below with the
+# same path classifiers used by Read and Write.
+_COPY_DEST = re.compile(r"(?i)(?:cp|mv|copy|move|copy-item|move-item)\Z")
+
+# These verbs take file operands. Pattern tools (select-string/sls, grep/rg/findstr/awk/sed) take
+# search patterns too, so matching an env-looking argument would block ordinary searches.
+# Known limits: free text containing both a verb and `.env` (for example a commit message saying
+# `never cat .env`) is denied; `git diff .env`, `git log -p .env`, bare `tee .env`, and
+# `docker --env-file` are not blocked. Command substitution
+# (`cat $(echo .env)`), PowerShell .NET file calls
+# (`[IO.File]::ReadAllText`), and scripts that open the file themselves are not parsed here.
+_ENV_READ = re.compile(
+    r"(?i)(?:cat|type|more|less|head|tail|get-content|gc|base64|xxd|od|strings|hexdump|sort|nl|tac|source|\.)\Z"
+)
+_INPUT_REDIRECT = re.compile(r"(?<!<)<(?!<)\s*([^\s|;&<>]+)")
+
+# python/node/etc. run inline with -c/-e that touches a `.env*` file, e.g. `open('.env')`.
+# The mandatory [\s'"/\\] immediately before "\.env" is load-bearing: without it, `.env` would
+# match inside `process.env.HOME` (preceded by "s" from "process") and deny an ordinary command
+# that merely mentions an environment VARIABLE, not the FILE. Found while testing this phase.
+_INLINE_ENV = re.compile(
+    r"(?i)\b(python\d?|py|node|ruby|perl)\b\s+(-c|-e)\s+.*[\s'\"/\\]\.env"
+    r"(?!\.(example|sample|template|dist))\b",
+    re.DOTALL,
+)
+
+
+def _copy_segments(c: str) -> list[str]:
+    """Segments of ``c`` split on ``;``, ``&&``, a bare newline and a bare ``|`` (quote/paren-aware).
+
+    Unlike ``_statements`` (used for the catastrophic-delete check), a pipe IS a boundary here:
+    `some_cmd | cp x .env` still has `cp x .env` naming its own destination at the end of ITS
+    segment, and `_COPY_DEST`'s trailing `$` anchor needs that segment on its own to match."""
+    c = _CONTINUATION.sub(" ", c)
+    out: list[str] = []
+    cur: list[str] = []
+    quote, depth, i = "", 0, 0
+    while i < len(c):
+        ch = c[i]
+        if quote:
+            quote = "" if ch == quote else quote
+        elif ch in "'\"":
+            quote = ch
+        elif ch in "({":
+            depth += 1
+        elif ch in ")}" and depth:
+            depth -= 1
+        elif depth == 0 and (ch in ";\n|" or c[i:i + 2] == "&&"):
+            out.append("".join(cur))
+            cur = []
+            i += 2 if c[i:i + 2] == "&&" else 1
+            continue
+        cur.append(ch)
+        i += 1
+    out.append("".join(cur))
+    return [_strip_quotes(s).strip() for s in out]
+
+
+def _shell_env_access(command: str) -> tuple[str, str]:
+    """Check simple shell file operands in one pass per command segment."""
+    for seg in _copy_segments(command):
+        # Redirection can precede or follow the command: `< .env cat` and `cat < .env`.
+        for match in _INPUT_REDIRECT.finditer(seg):
+            if classify_read(match.group(1))[0] == "deny":
+                return "deny", "shell command reads a secret env file"
+
+        words = seg.split()
+        for index, word in enumerate(words):
+            if word.lower() == "dd":
+                for arg in words[index + 1:]:
+                    if arg.startswith("if=") and classify_read(arg[3:])[0] == "deny":
+                        return "deny", "shell command reads a secret env file"
+                break
+
+            if word.lower() == "git" and index + 1 < len(words) and words[index + 1].lower() == "show":
+                for arg in words[index + 2:]:
+                    if ":" in arg and classify_read(arg.split(":", 1)[1])[0] == "deny":
+                        return "deny", "shell command reads a secret env file"
+                break
+
+            if _COPY_DEST.fullmatch(word):
+                operands: list[str] = []
+                destination = ""
+                i = index + 1
+                while i < len(words):
+                    arg = words[i]
+                    if arg.lower() in ("-path", "-literalpath", "-source", "-destination") and i + 1 < len(words):
+                        if arg.lower() == "-destination":
+                            destination = words[i + 1]
+                        else:
+                            operands.append(words[i + 1])
+                        i += 2
+                    elif not arg.startswith("-"):
+                        operands.append(arg)
+                        i += 1
+                    else:
+                        i += 1
+                if not destination and len(operands) >= 2:
+                    destination = operands.pop()
+                if destination and classify_write(destination)[0] == "deny":
+                    return "deny", f"shell command copies onto a secret file ({destination})"
+                if any(classify_read(source)[0] == "deny" for source in operands):
+                    return "deny", "shell command copies a secret env file"
+                break
+
+            if _ENV_READ.fullmatch(word):
+                if any(classify_read(path)[0] == "deny" for path in words[index + 1:]):
+                    return "deny", "shell command reads a secret env file"
+                break
+    return "allow", ""
+
+
 def classify_bash(command: str, root: str | None = None) -> tuple[str, str]:
     """Risk tier (deny|ask|allow) + reason for a shell command. ``root`` is the cwd the command runs in
     (default: this process's cwd); `git add <dir>` resolves against it."""
     c = command.strip()
+    data_free = _without_heredoc_bodies(c)
     cl = c.lower()
     n = _strip_quotes(c)          # quote-normalized: defeats `rm '-rf' "/"` evasion
     nl = n.lower()
+
+    # ── deny: copying or reading a secret env file through the shell (copied from hooks/guard.py) ──
+    _tier, _reason = _shell_env_access(_strip_quotes(data_free))
+    if _tier == "deny":
+        return _tier, _reason
+
+    # ── deny: writing a secret through the shell (copied from hooks/guard.py) ──
+    # The same file must not be denied via a write tool and waved through via `echo ... > .env`.
+    for _target in _shell_write_targets(data_free):
+        _tier, _why = classify_write(_target)
+        if _tier == "deny":
+            return "deny", f"shell command {_why}"
+
+    # ── deny: an inline python/node/etc. one-liner that touches a secret env file ──
+    if _INLINE_ENV.search(c):
+        return "deny", "inline interpreter touches a secret env file"
+
     rm_rf = _is_rm_recursive_force(n)
     find_delete = bool(re.search(_FIND_DELETE, nl))
     win_del = _is_win_recursive_delete(n)
@@ -691,15 +1202,22 @@ def classify_bash(command: str, root: str | None = None) -> tuple[str, str]:
         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"
-    data_free = _without_heredoc_bodies(c)
     _staging = _git_staging_safe(data_free, os.getcwd() if root is None else root)
     if _staging:
         return "deny", _staging
     _publish = _headless_publish_safe(data_free)
     if _publish:
         return "deny", _publish
+    _shared = _shared_checkout_safe(data_free, os.getcwd() if root is None else root)
+    if _shared and _headless():
+        return "deny", f"headless session: {_shared}"
 
     # ── ask: destructive-but-legit ──
+    _config = _config_shell_safe(data_free)
+    if _config:
+        return "ask", _config
+    if _shared:
+        return "ask", _shared
     if rm_rf:
         return "ask", "recursive force-delete (rm -rf)"
     if find_delete:
@@ -726,6 +1244,100 @@ def classify_bash(command: str, root: str | None = None) -> tuple[str, str]:
     return "allow", ""
 
 
+# Copied from hooks/guard.py: ── the shared-tree lock during a spawn-session handover ─────────────────────
+# `spawn-session.md` told the child not to move the shared checkout while both sessions are live.
+# The parent pasted it verbatim and the successor switched branches within the hour (2026-09-10);
+# four files the parent had corrected reverted under it. A rule that has to be remembered is not a
+# gate, so while a handshake is open the guard refuses the git commands that move or discard the
+# tree. DENY, not ask: deny-only mode turns every ask into a silent allow, and that is the mode the
+# failure happened in.
+#
+# The verb must be git's SUBCOMMAND (first word after global options), so `git commit -m "reset x"`
+# and `git worktree add ... -b feat` pass. `stash list` / `stash show` only read.
+_TREE_MOVING_GIT = re.compile(
+    r"\bgit(?:\s+-[Cc]\s+\S+|\s+--?[\w-]+(?:=\S+)?)*\s+"
+    r"(?:switch|checkout|restore|rebase|reset|clean|stash(?!\s+(?:list|show)\b))(?=\s|$|[;&|])",
+    re.I,
+)
+# Older than this is an abandoned handshake, not a live one — two REJECTs end a handshake that
+# `close` can never accept, and it must not lock the tree forever.
+_HANDSHAKE_LIVE_S = 24 * 3600
+
+
+def _open_handshake(start: str) -> str:
+    """Id of a spawn-session handshake still open in the repo holding ``start``, or ''."""
+    here = os.path.abspath(start)
+    while True:
+        d = os.path.join(here, _ARTIFACT_DIR, "spawn-session")
+        if os.path.isdir(d):
+            now = time.time()
+            try:
+                names = sorted(os.listdir(d))
+            except FileNotFoundError:  # gone since isdir: no handshake. Any other OSError reaches tree_lock_check.
+                return ""
+            for name in names:
+                if not name.endswith("-handshake.json"):
+                    continue
+                # A file that is not a lock (unreadable, not an object, no `tree_lock: true`) is skipped. It must
+                # never raise: the hook would fail closed and deny every tree-moving git command.
+                try:
+                    with open(os.path.join(d, name), encoding="utf-8") as fh:
+                        st = json.load(fh)
+                except Exception:
+                    continue
+                # `tree_lock` is written by handshakes opened since the lock existed. Older files
+                # never stamped `closed_at`, so without this opt-in a handshake finished under the
+                # old code would lock a live session's tree — measured on a real one, 11h old.
+                if not isinstance(st, dict) or st.get("tree_lock") is not True or st.get("closed_at"):
+                    continue
+                # An explicit open lock fails closed: a missing or bad `opened_at` is live, never abandoned.
+                try:
+                    opened = float(st["opened_at"])
+                except (KeyError, TypeError, ValueError):
+                    opened = now
+                if math.isfinite(opened) and now - opened > _HANDSHAKE_LIVE_S:
+                    continue
+                return str(st.get("id") or name[: -len("-handshake.json")])
+            return ""
+        parent = os.path.dirname(here)
+        if parent == here:
+            return ""
+        here = parent
+
+
+def tree_lock_check(command: str, root: str) -> tuple[str, str]:
+    """("deny", why) when ``command`` would move a checkout a live handshake shares; ("ask", why) when the handshake
+    folder cannot be read, so a live lock may be hidden; else ("", "")."""
+    m = _TREE_MOVING_GIT.search(command)
+    if not m:
+        return "", ""
+    # `git -C <path>` acts on <path>, not on the checkout the command was issued from.
+    target = re.search(r"\s-C\s+(\S+)", m.group(0))
+    if target:
+        root = os.path.join(root, target.group(1).strip("'\""))
+    try:
+        hs = _open_handshake(root)
+    except OSError as exc:
+        return "ask", (f"cannot read the spawn-session handshakes ({type(exc).__name__}), so another session may "
+                       "share this checkout; confirm that no handshake is open before you move the tree")
+    if not hs:
+        return "", ""
+    return "deny", _tree_lock_why(hs)
+
+
+def tree_lock_reason(command: str, root: str) -> str:
+    """The deny reason when ``command`` would move a checkout a live handshake shares, else ''."""
+    tier, why = tree_lock_check(command, root)
+    return why if tier == "deny" else ""
+
+
+def _tree_lock_why(hs: str) -> str:
+    return (f"spawn-session handshake `{hs}` is open, so two sessions share this checkout. Moving or "
+            "discarding the tree here carries or destroys the other session's uncommitted work. "
+            "Work in your own tree instead: `git worktree add <scratch>/<name> -b <branch> "
+            "origin/main`, and remove it when the work lands. The lock lifts at `handshake close`")
+
+
 # ── 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
@@ -741,6 +1353,11 @@ _PATH_ARG_KEYS = ("FilePath", "filePath", "file_path", "AbsolutePath", "absolute
                   "TargetFile", "targetFile", "Path", "path")
 
 
+def _is_write_tool(name: str) -> bool:
+    """A tool whose name looks like an edit/write and not like a read (the heuristic decide() uses)."""
+    return bool(_WRITE_NAME_RE.search(name)) and not _READONLY_NAME_RE.search(name)
+
+
 def _first_str(args: dict, keys) -> str:
     for k in keys:
         v = args.get(k)
@@ -761,7 +1378,7 @@ def decide(tool_name: str, args, allow_patterns: list[str], root: str | None = N
         target = _first_str(args, _COMMAND_ARG_KEYS)
         cwd = _first_str(args, _CWD_ARG_KEYS) or root  # the command's own cwd, else the workspace root
         tier, reason = classify_bash(target, cwd) if target else ("allow", "")
-    elif _WRITE_NAME_RE.search(name) and not _READONLY_NAME_RE.search(name):
+    elif _is_write_tool(name):
         target = _first_str(args, _PATH_ARG_KEYS)
         tier, reason = classify_write(target) if target else ("allow", "")
     else:
@@ -802,31 +1419,35 @@ def _load_allow(root: str) -> list[str]:
     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).
+def _env_off() -> bool:
+    return os.environ.get(f"{_ENV_PREFIX}_GUARD_DISABLED", "").strip().lower() in _TRUTHY
+
+
+def _config_off(section: dict) -> bool:
+    """A config off switch in the ``[guard]`` table: ``enabled = false`` or ``mode = "off"``."""
+    return section.get("enabled") is False or str(section.get("mode", "")).strip().lower() == "off"
 
-    Precedence: the env var wins (global); otherwise the per-repo `[guard]` table — `enabled = false`
-    or `mode = "off"`. Any parse problem → not disabled (fail safe). Env var: CADDIS_GUARD_DISABLED."""
-    _disabled = os.environ.get(f"{_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 guard_disabled(root: str | None = None) -> bool:
+    """True when the guard is turned off entirely (all tiers bypassed): env CADDIS_GUARD_DISABLED, interactively.
+
+    Robustness #13: the config file cannot do this any more (a model can write it; see ``deny_only``), and a
+    headless session ignores the env var too. ``root`` is kept for callers; the answer no longer reads it."""
+    return _env_off() and not _headless()
 
 
 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`; config `[guard] mode = "deny-only"`. Read silently."""
+    """True when the guard keeps DENY (silent hard-block of catastrophes) but suppresses the ASK tier
+    (downgrades ask -> allow), so it NEVER prompts. For autonomous / no-prompt workflows that still
+    want a catastrophe net: a big plan runs uninterrupted, only a truly destructive call is blocked.
+
+    On: env ``CADDIS_GUARD_MODE=deny-only``; config ``[guard] mode = "deny-only"``; a config off switch
+    (``enabled = false`` / ``mode = "off"``); the env off switch in a headless session. Read silently."""
     _mode = os.environ.get(f"{_ENV_PREFIX}_GUARD_MODE", "")
-    if _mode.strip().lower() == "deny-only":
+    if _mode.strip().lower() == "deny-only" or (_env_off() and _headless()):
         return True
     section = _load_guard_config(root)
-    return str(section.get("mode", "")).strip().lower() == "deny-only"
+    return _config_off(section) or str(section.get("mode", "")).strip().lower() == "deny-only"
 
 
 # ── hook I/O glue (agy envelope) ─────────────────────────────────────────────
@@ -883,11 +1504,21 @@ def _workspace_roots(data):
         return []
     return [str(r) for r in roots if isinstance(r, (str, bytes)) and str(r).strip()]
 
-def headless_publish_decision(tool_name: str, args) -> str:
-    """The headless publish deny reason for a shell tool call, else ''. Used when the guard is switched off."""
-    if (tool_name or "").strip().lower() not in _COMMAND_TOOLS or not isinstance(args, dict):
-        return ""
-    return _headless_publish_safe(_without_heredoc_bodies(_first_str(args, _COMMAND_ARG_KEYS).strip()))
+def decide_call(tool_name: str, args, allow_patterns: list[str], root: str) -> tuple[str, str]:
+    """decide() plus the spawn-session tree lock for a shell call (guard.py applies it in hook_decision)."""
+    tier, reason = decide(tool_name, args, allow_patterns, root)
+    if tier != "deny" and (tool_name or "").strip().lower() in _COMMAND_TOOLS and isinstance(args, dict):
+        cwd = _first_str(args, _CWD_ARG_KEYS) or root  # the command's own cwd wins, as in decide()
+        lock_tier, lock = tree_lock_check(_first_str(args, _COMMAND_ARG_KEYS), cwd)
+        if lock_tier == "deny" or (lock_tier == "ask" and tier == "allow"):
+            tier, reason = lock_tier, lock
+    return tier, reason
+
+
+def _fails_closed(tool_name: str) -> bool:
+    """A shell or write call: an internal error while judging it denies it (robustness #13)."""
+    name = (tool_name or "").strip().lower()
+    return name in _COMMAND_TOOLS or _is_write_tool(name)
 
 
 def main() -> None:
@@ -899,46 +1530,47 @@ def main() -> None:
                 _reconfig(encoding="utf-8")
             except Exception as _exc:
                 _hook_note("agy stdout utf-8 reconfigure", _exc)
+        # Silent ONLY for a payload it cannot read: there is no call to judge.
         try:
             data = json.load(sys.stdin)
-        except Exception:
-            return  # malformed payload → fail open, silently
+        except ValueError as _exc:  # JSONDecodeError and UnicodeDecodeError are ValueErrors
+            _hook_note("agy guard unparseable payload", _exc)
+            return
         if not isinstance(data, dict):
             return
         call = data.get("toolCall")
         if not isinstance(call, dict):
             return
+        name, args = str(call.get("name") or ""), call.get("args")
         roots = _workspace_roots(data) or [os.getcwd()]
-
-        # Every per-repo guard setting RELAXES the guard: `enabled = false` bypasses all
-        # tiers, `mode = "deny-only"` drops the ask tier, and `[guard] allow` downgrades an
-        # ask. Reading them from workspacePaths[0] meant one repo's relaxation silently
-        # applied to every other repo in the workspace — repo A's kill switch unguarding
-        # repo B. Require UNANIMITY instead: a relaxation applies only when every root asks
-        # for it. One root is the common case and behaves exactly as before.
-        if all(guard_disabled(r) for r in roots):
-            # Kill switch: bypass every tier. Not for a headless session's push, merge or publish (robustness #4):
-            # a session can write .caddis/config.toml itself.
-            why = headless_publish_decision(str(call.get("name") or ""), call.get("args"))
-            if why:
-                tier, reason = "deny", why
-            return
-
-        # The allow-list downgrades an ask, so with several roots take only the entries
-        # present in ALL of them — the strictest reading, not the most permissive.
-        allow = _load_allow(roots[0])
-        for other in roots[1:]:
-            allow = [a for a in allow if a in _load_allow(other)]
-
-        # A path such as `git add src` may sit in any workspace root: decide once per root, keep the strictest.
-        # (guard.py has one cwd. A run_command `Cwd` argument wins inside decide, so every root agrees then.)
-        _rank = {"deny": 0, "ask": 1}
-        tier, reason = min((decide(str(call.get("name") or ""), call.get("args"), allow, r) for r in roots),
-                           key=lambda d: _rank.get(d[0], 2))
-        if tier == "ask" and all(deny_only(r) for r in roots):
-            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
+        try:
+            # Only the interactive env var turns the guard fully off (robustness #13); a config file cannot.
+            if guard_disabled(roots[0]):
+                return
+
+            # Every per-repo guard setting RELAXES the guard: `mode = "deny-only"` (and now a config off switch)
+            # drops the ask tier, and `[guard] allow` downgrades an ask. Reading them from workspacePaths[0]
+            # meant one repo's relaxation silently applied to every other repo in the workspace. Require
+            # UNANIMITY instead: a relaxation applies only when every root asks for it.
+            # The allow-list downgrades an ask, so with several roots take only the entries
+            # present in ALL of them — the strictest reading, not the most permissive.
+            allow = _load_allow(roots[0])
+            for other in roots[1:]:
+                allow = [a for a in allow if a in _load_allow(other)]
+
+            # A path such as `git add src` may sit in any workspace root: decide once per root, keep the strictest.
+            # (guard.py has one cwd. A run_command `Cwd` argument wins inside decide, so every root agrees then.)
+            _rank = {"deny": 0, "ask": 1}
+            tier, reason = min((decide_call(name, args, allow, r) for r in roots),
+                               key=lambda d: _rank.get(d[0], 2))
+            if tier == "ask" and all(deny_only(r) for r in roots):
+                tier = "allow"  # deny-only: keep catastrophe blocks, never force_ask (no plan interruption)
+        except Exception as _exc:  # noqa: BLE001 - fail CLOSED for a shell or write call, open otherwise
+            _hook_note("agy guard decision", _exc, roots[0])
+            tier, reason = ("deny", f"guard error: {type(_exc).__name__}: {str(_exc)[:120]}")                 if _fails_closed(name) else ("allow", "")
+    except Exception as _exc:
+        _hook_note("agy guard payload", _exc)
+        tier, reason = "allow", ""  # a payload shape it cannot read: no call to judge, never a crash
     finally:
         try:
             _emit(tier, reason)