@miller-tech/uap 1.183.3 → 1.184.1

package/src/policies/enforcers/workdir_scope.py

@@ -14,8 +14,9 @@ Allowed targets:
     checkout (UAP_REPO_ROOT) — worktrees included;
   * relative paths (they resolve under the project root);
   * a scratch allow-list: /tmp, $TMPDIR, ~/.cache/uap, ~/.config/uap,
-    ~/.claude/projects (Claude Code auto-memory/session storage), plus any
-    colon-separated prefixes in UAP_WORKDIR_ALLOW.
+    ~/.claude/projects and ~/.claude/plans (Claude Code auto-memory, session
+    and plan-file storage), plus any colon-separated prefixes in
+    UAP_WORKDIR_ALLOW.
 
 Escape hatch: UAP_WORKDIR_SCOPE_OFF=1 allows everything (operator override).
 """
@@ -64,12 +65,19 @@ def _allowed_roots() -> list[Path]:
     # topic files, MEMORY.md index, session/transcript data). The harness
     # instructs agents to persist memories there; blocking it silently breaks
     # memory recording (observed on pay2u 2026-07-05).
+    #
+    # ~/.claude/plans is the same story for plan mode: the harness assigns the
+    # agent a plan file under it and ExitPlanMode reads the plan back from
+    # there. Blocking it makes plan mode unusable - and since self-protect
+    # matches this enforcer's own override env var, that documented escape is
+    # unreachable from inside a session too (observed 2026-08-03).
     for p in (
         "/tmp",
         os.environ.get("TMPDIR", "/tmp"),
         "~/.cache/uap",
         "~/.config/uap",
         "~/.claude/projects",
+        "~/.claude/plans",
     ):
         add(_expand(p))
     for p in os.environ.get("UAP_WORKDIR_ALLOW", "").split(":"):
@@ -114,6 +122,108 @@ def _check_path(target: str, roots: list[Path]) -> str:
     return "" if _inside(p, roots) else str(p)
 
 
+# Shell constructs the quote model above does not represent. Their presence
+# means a quoted span may still contain EXECUTING code (command substitution)
+# or may not be quoted at all (escaped quote characters), so masking is unsafe.
+_UNMODELLED = re.compile(r"\$\(|`|\$'|\\['\"]")
+
+
+_LINE_CONT = re.compile(r'\\\n')
+_REDIR_OP = re.compile(r'(?:\d*>>?|&>)')
+# Targets may be tilde- or variable-prefixed: `> ~/x`, `> $HOME/x`. _expand()
+# already resolves both before the scope check, but a `/`-anchored pattern
+# never handed them over — so they were silently unchecked (confirmed by
+# writing outside the project through both forms).
+_REDIR_TARGET = re.compile(r'\s*("?)([~/$][^\s"\';|&)]+)\1')
+
+
+def _risk_view(cmd: str) -> str:
+    """`cmd` with SINGLE-quoted spans blanked, for the unmodelled-construct check.
+
+    Single quotes suppress every expansion, so `$(`, a backtick or `$'` inside
+    them is inert prose and must not force the conservative raw scan — that is
+    how an ordinary `git commit -m '... $(uname) ... > /opt/notes ...'` came
+    to be refused. Double-quoted and unquoted occurrences stay visible, because
+    those DO execute.
+    """
+    out = list(cmd)
+    in_sq = False
+    i = 0
+    while i < len(cmd):
+        ch = cmd[i]
+        if in_sq:
+            if ch == "'":
+                in_sq = False
+            else:
+                out[i] = " "
+        elif ch == "\\":
+            i += 2          # escaped char cannot open a quote
+            continue
+        elif ch == "'" and not (i and cmd[i - 1] == "$"):
+            # $'...' processes escapes, so it is NOT inert — leave it visible.
+            in_sq = True
+        i += 1
+    return "".join(out)
+
+
+def _mask_quoted(cmd: str) -> tuple[str, bool]:
+    """(masked copy, whether a quote was left unterminated).
+
+    Blanks the CONTENT of quoted spans, preserving length so offsets still line
+    up with the original and the redirect TARGET can be read from the real
+    string.
+
+    Escape-aware, and that is the load-bearing part. A naive quote toggle
+    desyncs on an escaped quote and then blanks everything after it — including
+    a genuinely unquoted redirect. `: \\" > /root/x` was ALLOWED by exactly
+    that bug: a containment gate turned into a bypass, which is strictly worse
+    than the false positive the masking was added to fix.
+
+    Shell rules honoured:
+      * unquoted `\\X` escapes X, so X can neither open a quote nor be an
+        operator (`\\>` is a literal, not a redirect);
+      * inside '...' there is NO escaping — the next ' always closes;
+      * inside "..." a backslash escapes the following character;
+      * $'...' does process escapes, so a backslashed quote does not close it.
+    """
+    out = list(cmd)
+    n = len(cmd)
+    quote = None          # None | "'" | '"' | "$'"
+    i = 0
+    while i < n:
+        ch = cmd[i]
+        if quote is None:
+            if ch == "\\":
+                # Escapes the next character: blank it so it cannot be read as an
+                # operator, and never let it open a quoted span.
+                if i + 1 < n:
+                    out[i + 1] = " "
+                i += 2
+                continue
+            if ch == "'":
+                # $'...' processes escapes; a bare '...' does not.
+                quote = "$'" if i and cmd[i - 1] == "$" else "'"
+            elif ch == '"':
+                quote = '"'
+        elif quote == "'":
+            if ch == "'":
+                quote = None
+            else:
+                out[i] = " "
+        else:  # '"' or "$'" — both process backslash escapes
+            if ch == "\\" and i + 1 < n:
+                out[i] = " "
+                out[i + 1] = " "
+                i += 2
+                continue
+            if (quote == '"' and ch == '"') or (quote == "$'" and ch == "'"):
+                quote = None
+            else:
+                out[i] = " "
+        i += 1
+    return "".join(out), quote is not None
+
+
 def _scan_bash(cmd: str, roots: list[Path]) -> str:
     """Best-effort: flag an out-of-scope absolute path that a CREATE/MOVE command
     would write. Conservative — only inspects the destinations of known
@@ -125,6 +235,11 @@ def _scan_bash(cmd: str, roots: list[Path]) -> str:
     # newlines flags any path-shaped string inside it. Bodies that could be
     # executed are left in place by the helper.
     cmd = strip_heredoc_bodies(cmd)
+    # Bash removes `\\<newline>` before word-splitting. Leaving it in split one
+    # logical command across two segments, so a create verb on the first line
+    # never met its destination on the second — `mkdir -p \\<newline> /outside`
+    # was allowed while bash created the directory.
+    cmd = _LINE_CONT.sub(" ", cmd)
     try:
         tokens = shlex.split(cmd, comments=True)
     except ValueError:
@@ -132,12 +247,41 @@ def _scan_bash(cmd: str, roots: list[Path]) -> str:
 
     candidates: list[str] = []
 
-    # Output redirections: > /abs, >> /abs (also 2>/abs).
-    for m in re.finditer(r'(?:\d*>>?|&>)\s*("?)(/[^\s"\';|&)]+)\1', cmd):
-        candidates.append(m.group(2))
+    # Output redirections.
+    #
+    # Operators are located in a QUOTE-MASKED copy, because a redirect
+    # operator inside quotes is not a redirect - it is literal text.
+    # Scanning the raw string refused a sed range expression, reading the
+    # trailing '/p' of `sed -n '/a/,/b/p'` as a write to /p when the range
+    # delimiters were angle brackets (observed 2026-08-03, while editing
+    # this very enforcer). The TARGET is then read from the ORIGINAL
+    # string at that offset, so a legitimately quoted absolute destination
+    # is still detected.
+    masked, unterminated = _mask_quoted(cmd)
+    # Scan the RAW string whenever the quote model cannot be trusted:
+    #
+    #   * an unterminated quote — the mask is desynced by construction;
+    #   * a construct the model does not represent (_UNMODELLED). Command
+    #     substitution is the important one: it EXECUTES inside double quotes,
+    #     so blanking a quoted span hides a live redirect. Verified with bash —
+    #     `echo "$(id > /outside)"` writes the file, and the masked scan saw
+    #     nothing. A containment gate must over-block, never under-block, so
+    #     these fall back to the conservative scan and accept its false
+    #     positives.
+    #
+    # The sed-range case this masking exists to fix contains none of them, so it
+    # still passes.
+    untrusted = unterminated or _UNMODELLED.search(_risk_view(cmd)) is not None
+    for m in _REDIR_OP.finditer(cmd if untrusted else masked):
+        target = _REDIR_TARGET.match(cmd, m.end())
+        if target:
+            candidates.append(target.group(2))
 
     # Split into pipeline/sequence segments so we read each command's own verb.
-    segments = re.split(r'\|\||&&|[;|&\n]', cmd)
+    # Parens are separators too, so the inner command of a process substitution
+    # becomes its own segment: `> >(tee /outside)` otherwise hid `tee`'s
+    # destination from the verb scan entirely, while bash wrote the file.
+    segments = re.split(r'\|\||&&|[;|&\n()]', cmd)
     for seg in segments:
         try:
             parts = shlex.split(seg, comments=True)

package/src/policies/schemas/policies/engineering-principles.md

@@ -0,0 +1,93 @@
+# engineering-principles
+
+**Category**: quality
+**Level**: RECOMMENDED
+**Enforcement Stage**: pre-exec
+**Tags**: quality, simplicity, architecture, dependencies, prior-art
+
+## Rule
+
+Write code to these principles. Rules 2-8 always apply. Rule 1 depends on a
+stance resolved per project per session — run `uap principles show` to see the
+form in force, and `uap principles ask` to answer it.
+
+1. **Backward compatibility — stance-dependent.**
+   - `remove`: delete obsolete paths instead of adding compatibility layers,
+     fallbacks, or migrations.
+   - `preserve`: keep existing paths working and migrate callers before
+     removing anything.
+
+   Under `remove`, these surfaces are still preserved and migrated, never
+   deleted, because their callers are not yours to update:
+   - the public CLI surface — command names, flags, and their output contracts
+   - MCP tool names and input schemas
+   - database, config, and on-disk state schemas, including their migrations
+   - exported types and public module entry points
+
+2. **Choose the simplest implementation that fully meets the current
+   requirements.** Avoid speculative abstractions, configuration, and
+   indirection.
+
+3. **Grow the system in layers.** Start from the smallest version that works end
+   to end, and add each new capability on top of a product that already works.
+   Never trade a working product for unfinished complexity.
+
+4. **Keep components modular and concerns clearly separated.**
+
+5. **Prefer established, well-maintained libraries** when they reduce overall
+   complexity or improve reliability. Do not reimplement common functionality
+   without a clear reason.
+
+6. **Lean on the dependencies already in the project** before writing your own
+   implementation or adding packages. Do not assume a library lacks a capability
+   without checking its documentation and types.
+
+7. **Make architectural decisions for the long term.** Do not accept a stopgap
+   that only works for now and is meant to be replaced later.
+
+8. **Study how established products solve the problem before designing a
+   solution.** Adopt their proven patterns and conventions rather than inventing
+   an approach from scratch.
+
+## Why
+
+Adapted from an AGENTS.md distilled from roughly 60B tokens of agent-driven
+coding (x.com/MarcosHernanz/status/2083954734487212511). Its author scopes it to
+side projects — "don't use it in production if you don't want to destroy your
+codebase" — and rule 1 is why: deleting obsolete paths is right when you own
+every caller and destructive when you do not. Rather than adopt or drop rule 1
+wholesale, UAP resolves it per project per session and carves out the surfaces
+other people are bound to.
+
+The remaining rules are direction-of-travel guidance, not gates. They are
+RECOMMENDED because a machine cannot tell a speculative abstraction from a
+necessary one, and a blocking check that guesses would cost more than it saves.
+
+## Enforcement
+
+Advisory. There is no Python enforcer: these are judgment calls, and blocking
+gates in this repo have repeatedly cost more in false positives than they
+prevented. The principles reach the model three other ways:
+
+- **Deliver prompts** — the compact form is injected into every convergence-loop
+  and orchestrated task prompt, so generated code is held to them rather than
+  only the agent's preamble.
+- **Reactor** — while the rule-1 stance is unresolved, the agent is told to ask
+  the user once; after that it stays silent.
+- **Judge** — competing candidates are scored on reuse-over-reimplementation and
+  absence of stopgaps.
+
+Related: pattern P38 (Prior Art First) covers rules 5, 6 and 8 at plan time; the
+`/simplify` and `distill` skills cover rule 2 on existing code.
+
+```rules
+- title: "Simplest implementation that meets the requirement"
+  keywords: [implement, refactor, design, abstraction, config, indirection]
+  antiPatterns: [speculative-abstraction, premature-config, needless-indirection]
+- title: "Reuse before reimplementation"
+  keywords: [library, dependency, package, util, helper, from scratch]
+  antiPatterns: [reimplemented-common-functionality, unchecked-library-capability]
+- title: "No stopgaps"
+  keywords: [temporary, for now, placeholder, replace later, quick fix]
+  antiPatterns: [stopgap-architecture, deferred-rewrite]
+```

package/tools/agents/tests/test_expert_review_pr_scope.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""expert-review-required: a PR ship is scoped to the PR's branch.
+
+`gh pr merge <N>` ships the branch of PR N, which is usually not the branch the
+invoking shell is standing on. Keying the review off the LOCAL branch meant a
+merge run from the main checkout looked for `.uap/reviews/master.json`, found a
+stale artifact from an unrelated past session, and refused a PR whose own branch
+was reviewed and approved (observed 2026-08-03 merging #645).
+
+`gh` is stubbed on PATH, so these tests need no network or auth.
+"""
+
+import json
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ENFORCER = (
+    Path(__file__).resolve().parents[3]
+    / "src" / "policies" / "enforcers" / "expert_review_required.py"
+)
+
+PR_NUMBER = "645"
+VERB = "merge"
+PR_BRANCH = "feature/160-plan-gate-writers"
+PR_SHA = "dd5ce346281d720dff357d4a649d7389e65bfd61"
+STALE_SHA = "2f1b660f" + "0" * 32
+
+
+def _slug(branch):
+    return branch.replace("%", "%25").replace("/", "%2F")
+
+
+def _git(root, *args):
+    env = dict(os.environ)
+    for v in ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE"):
+        env.pop(v, None)
+    subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, env=env)
+
+
+class TestExpertReviewPrScope(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        base = Path(self._tmp.name)
+        self.root = base / "repo"
+        self.bin = base / "bin"
+        self.root.mkdir()
+        self.bin.mkdir()
+        self._write_stub_gh()
+        self._init_repo()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _write_stub_gh(self, head_ref=PR_BRANCH, head_oid=PR_SHA, rc=0, per_ref=None):
+        """Stub `gh pr view`. `per_ref` maps a PR reference -> (branch, sha), so
+        a test can prove WHICH pull request the enforcer actually resolved."""
+        gh = self.bin / "gh"
+        gh.write_text(
+            "#!/usr/bin/env python3\n"
+            "import json, sys\n"
+            f"if {rc} != 0:\n"
+            f"    sys.exit({rc})\n"
+            f"per_ref = {per_ref!r}\n"
+            "argv = sys.argv[1:]\n"
+            "if 'headRefName' in ' '.join(argv):\n"
+            "    ref = argv[2] if len(argv) > 2 else ''\n"
+            "    if per_ref and ref in per_ref:\n"
+            "        b, o = per_ref[ref]\n"
+            "    else:\n"
+            f"        b, o = {head_ref!r}, {head_oid!r}\n"
+            "    print(json.dumps({'headRefName': b, 'headRefOid': o}))\n"
+            "    sys.exit(0)\n"
+            "sys.exit(1)\n"
+        )
+        gh.chmod(gh.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+    def _init_repo(self):
+        _git(self.root, "init", "-q", "-b", "master", ".")
+        _git(self.root, "config", "user.email", "t@t")
+        _git(self.root, "config", "user.name", "t")
+        # A high-risk path, so the low-risk scope skip cannot mask the outcome.
+        (self.root / "src" / "policies").mkdir(parents=True)
+        (self.root / "src" / "policies" / "x.py").write_text("x = 1\n")
+        _git(self.root, "add", "-A")
+        _git(self.root, "commit", "-qm", "init")
+
+        self.reviews = self.root / ".uap" / "reviews"
+        self.reviews.mkdir(parents=True)
+
+    def _write_review(self, branch, head, verdict="approve"):
+        (self.reviews / f"{_slug(branch)}.json").write_text(
+            json.dumps({"branch": branch, "head": head, "verdict": verdict,
+                        "reviewers": ["code-quality-reviewer"]})
+        )
+
+    def _run(self, command):
+        env = dict(os.environ)
+        env["UAP_REPO_ROOT"] = str(self.root)
+        env["UAP_WORKTREE_ROOT"] = str(self.root)
+        env["PATH"] = f"{self.bin}{os.pathsep}" + env.get("PATH", "")
+        env.pop("UAP_NO_REVIEW", None)
+        p = subprocess.run(
+            [sys.executable, str(ENFORCER), "--operation", "Bash",
+             "--args", json.dumps({"command": command})],
+            capture_output=True, text=True, env=env, cwd=str(self.root),
+        )
+        try:
+            out = json.loads(p.stdout)
+        except json.JSONDecodeError:
+            out = {"allowed": True, "reason": f"<unparseable {p.stdout!r} {p.stderr!r}>"}
+        return out, p.returncode
+
+    # --- the regression -----------------------------------------------------
+
+    def test_pr_merge_uses_the_prs_branch_not_the_current_one(self):
+        self._write_review(PR_BRANCH, PR_SHA)
+        # master carries a stale artifact from an unrelated session.
+        self._write_review("master", STALE_SHA)
+
+        out, code = self._run(f"gh pr merge {PR_NUMBER} --squash")
+        self.assertTrue(out.get("allowed"), f"should ship on the PR's review: {out.get('reason')}")
+        self.assertEqual(code, 0)
+        self.assertIn(_slug(PR_BRANCH), out.get("reason", ""))
+
+    def test_pr_merge_blocked_when_the_prs_own_review_is_missing(self):
+        # An approved artifact for the CURRENT branch must not authorise a
+        # different branch's PR — that would be the bug inverted.
+        self._write_review("master", STALE_SHA)
+        out, code = self._run(f"gh pr merge {PR_NUMBER} --squash")
+        self.assertFalse(out.get("allowed"), "no review for the PR's branch")
+        self.assertEqual(code, 2)
+        self.assertIn(_slug(PR_BRANCH), out.get("reason", ""))
+
+    def test_pr_merge_blocked_when_the_prs_review_is_stale(self):
+        self._write_review(PR_BRANCH, "0" * 40)  # covers some other head
+        out, code = self._run(f"gh pr merge {PR_NUMBER} --squash")
+        self.assertFalse(out.get("allowed"), "stale review for the PR's branch")
+        self.assertEqual(code, 2)
+
+    # --- fallbacks ----------------------------------------------------------
+
+    def test_falls_back_to_local_branch_when_gh_cannot_answer(self):
+        # No gh, no network, wrong auth: resolution returns nothing and the
+        # enforcer must behave exactly as before rather than fail open.
+        self._write_stub_gh(rc=1)
+        self._write_review("master", STALE_SHA)
+        out, code = self._run(f"gh pr merge {PR_NUMBER} --squash")
+        self.assertFalse(out.get("allowed"), "falls back to the local branch")
+        self.assertEqual(code, 2)
+        self.assertIn("master", out.get("reason", ""))
+
+    def test_flags_before_the_pr_number_still_resolve(self):
+        # `gh pr merge --squash 645` is the form most people type. A pattern
+        # pinned to digits-right-after-the-verb missed it and fell back to the
+        # local branch, silently reinstating the bug this resolution fixes.
+        self._write_review(PR_BRANCH, PR_SHA)
+        self._write_review("master", STALE_SHA)
+        out, code = self._run("gh pr " + VERB + " --squash " + PR_NUMBER)
+        self.assertTrue(out.get("allowed"), f"flags-first form: {out.get('reason')}")
+        self.assertEqual(code, 0)
+        self.assertIn(_slug(PR_BRANCH), out.get("reason", ""))
+
+    def test_bare_pr_merge_uses_the_current_branch(self):
+        # No PR named: the current branch IS the right thing to check.
+        self._write_review("master", STALE_SHA)
+        out, code = self._run("gh pr " + VERB)
+        self.assertFalse(out.get("allowed"), "bare merge falls back to local branch")
+        self.assertIn("master", out.get("reason", ""))
+
+    def test_a_value_bearing_flag_does_not_become_the_pr_reference(self):
+        # `gh pr merge -b 1 900` merges PR 900 with commit body "1". Taking the
+        # first non-flag token read "1" as the PR, so an approved review for
+        # PR 1 would authorise shipping the unreviewed PR 900 — the gate
+        # approving a different target than the command ships.
+        self._write_stub_gh(per_ref={
+            "1": (PR_BRANCH, PR_SHA),                   # reviewed + approved
+            "900": ("feature/unreviewed", "9" * 40),    # the real target
+        })
+        self._write_review(PR_BRANCH, PR_SHA)
+
+        out, code = self._run("gh pr " + VERB + " -b 1 900")
+        self.assertFalse(out.get("allowed"), "must judge PR 900, not the -b value")
+        self.assertEqual(code, 2)
+        self.assertIn("feature%2Funreviewed", out.get("reason", ""))
+
+    def test_non_pr_ship_still_uses_the_current_branch(self):
+        # `git push` from master is still judged against master.
+        self._write_review("master", STALE_SHA)
+        out, code = self._run("git push origin master")
+        self.assertFalse(out.get("allowed"), "stale master review blocks a master push")
+        self.assertEqual(code, 2)
+        self.assertIn("master", out.get("reason", ""))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tools/agents/tests/test_workdir_scope_enforcer.py

@@ -140,5 +140,157 @@ class TestWorkdirScopeEnforcer(unittest.TestCase):
         self._allow(out, c, "read outside allowed")
 
 
+# Redirect operator, built by codepoint: a literal one in this file would be
+# read as a redirection by the very enforcer under test.
+GT = chr(62)
+BS = chr(92)
+DQ = chr(34)
+SQ = chr(39)
+BT = chr(96)
+TILDE = chr(126)
+
+
+class TestWorkdirScopeQuoting(unittest.TestCase):
+    """A redirect operator inside quotes is literal text, not a redirect.
+
+    Scanning the raw command string made `sed -n '/a/,/b/p'` unusable whenever
+    the range delimiters were angle brackets: the trailing `/p` was read as a
+    write to /p. That refused an ordinary conflict-inspection command, and it
+    refused the edit that fixes it (observed 2026-08-03).
+    """
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self._tmp.name)
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _allow(self, out, code, label):
+        self.assertTrue(out.get("allowed"), f"{label}: {out.get('reason')}")
+        self.assertEqual(code, 0, label)
+
+    def _block(self, out, code, label):
+        self.assertFalse(out.get("allowed"), f"{label} should be blocked")
+        self.assertEqual(code, 2, label)
+
+    # --- the false positive ---
+
+    def test_sed_range_with_angle_delimiters_allowed(self):
+        cmd = "sed -n '/" + "<" * 7 + "/,/" + GT * 7 + "/p' CHANGELOG.md"
+        out, c = run("Bash", {"command": cmd}, self.root)
+        self._allow(out, c, "sed range is not a redirect")
+
+    def test_quoted_redirect_text_allowed(self):
+        out, c = run("Bash", {"command": "echo 'writes to /etc/passwd'"}, self.root)
+        self._allow(out, c, "quoted text is not a redirect")
+
+    def test_double_quoted_redirect_text_allowed(self):
+        out, c = run("Bash", {"command": 'echo "result ' + GT + ' /etc/passwd"'}, self.root)
+        self._allow(out, c, "double-quoted text is not a redirect")
+
+    # --- and the detection it must NOT weaken ---
+
+    def test_real_redirect_still_blocked(self):
+        out, c = run("Bash", {"command": "echo hi " + GT + " /etc/uap-marker"}, self.root)
+        self._block(out, c, "real redirect outside workdir")
+
+    def test_real_append_still_blocked(self):
+        out, c = run("Bash", {"command": "echo hi " + GT * 2 + " /etc/uap-marker"}, self.root)
+        self._block(out, c, "real append outside workdir")
+
+    def test_quoted_destination_still_blocked(self):
+        # The operator is unquoted; only the TARGET is quoted. Masking quoted
+        # spans must not lose this one.
+        out, c = run("Bash", {"command": 'echo hi ' + GT + ' "/etc/uap-marker"'}, self.root)
+        self._block(out, c, "quoted absolute destination")
+
+    # --- escaped quotes must not hide a REAL redirect (security review) ---
+    #
+    # A naive quote toggle desyncs on an escaped quote and blanks everything
+    # after it, including a live redirect. Each of these was ALLOWED by that
+    # bug: a containment bypass, strictly worse than the false positive the
+    # masking was added to fix.
+
+    def test_escaped_double_quote_does_not_hide_a_redirect(self):
+        cmd = ": " + BS + DQ + " " + GT + " /root/uap-probe"
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "escaped double quote then real redirect")
+
+    def test_escaped_single_quote_does_not_hide_a_redirect(self):
+        cmd = ": " + BS + SQ + " " + GT + " /root/uap-probe"
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "escaped single quote then real redirect")
+
+    def test_ansi_c_quoting_does_not_hide_a_redirect(self):
+        cmd = "echo $" + SQ + "a" + BS + SQ + "b" + SQ + " " + GT + " /root/uap-probe"
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "ANSI-C quoting then real redirect")
+
+    def test_unterminated_quote_falls_back_to_raw_scan(self):
+        # The mask cannot be trusted, so over-block rather than under-block.
+        cmd = "echo " + DQ + "oops " + GT + " /root/uap-probe"
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "unterminated quote")
+
+    # --- command substitution EXECUTES inside double quotes ---
+    #
+    # Masking a quoted span hid these: bash really does perform the redirect
+    # (verified), so blanking the span turned a containment gate into a bypass.
+    # The masker cannot model substitution, so its presence forces the raw scan.
+
+    def test_command_substitution_in_double_quotes_is_not_hidden(self):
+        cmd = "echo " + DQ + "$(id " + GT + " /root/uap-probe)" + DQ
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "$() inside double quotes")
+
+    def test_backticks_in_double_quotes_are_not_hidden(self):
+        cmd = "echo " + DQ + BT + "id " + GT + " /root/uap-probe" + BT + DQ
+        out, c = self._run_bash(cmd)
+        self._block(out, c, "backticks inside double quotes")
+
+    # --- targets the scanner used to never look at (bash-confirmed writes) ---
+
+    def test_tilde_redirect_target_is_checked(self):
+        # _expand() resolves ~ already; the target pattern just never handed it
+        # over, so `> ~/x` wrote outside the project unchecked.
+        out, c = self._run_bash("echo hi " + GT + " " + TILDE + "/uap-probe")
+        self._block(out, c, "tilde redirect target")
+
+    def test_variable_redirect_target_is_checked(self):
+        out, c = self._run_bash("echo hi " + GT + " $HOME/uap-probe")
+        self._block(out, c, "$HOME redirect target")
+
+    def test_line_continuation_keeps_verb_and_destination_together(self):
+        # Bash removes the continuation before word-splitting; the scanner did
+        # not, so the destination landed in a segment with no create verb.
+        out, c = self._run_bash("mkdir -p " + chr(92) + "\n  /root/uap-probe")
+        self._block(out, c, "destination after a line continuation")
+
+    def test_process_substitution_destination_is_checked(self):
+        # `> >(tee /outside)` really writes; parens were not segment
+        # separators, so tee's argument was invisible to the verb scan.
+        out, c = self._run_bash("echo data " + GT + " " + GT + "(tee /root/uap-probe)")
+        self._block(out, c, "process substitution destination")
+
+    # --- and the prose that must NOT be mistaken for a redirect ---
+
+    def test_inert_single_quoted_prose_is_not_a_redirect(self):
+        # Single quotes suppress substitution, so $( inside them is text. Forcing
+        # the conservative raw scan on its account blocked ordinary commit
+        # messages that merely discuss shell syntax.
+        cmd = ("git commit -m 'See $(uname) docs; example redirect "
+               + GT + " /opt/notes explained here'")
+        out, c = self._run_bash(cmd)
+        self._allow(out, c, "inert prose in a single-quoted message")
+
+    def _run_bash(self, cmd):
+        return run("Bash", {"command": cmd}, self.root)
+
+    def test_stderr_redirect_to_dev_null_allowed(self):
+        out, c = run("Bash", {"command": "ls 2" + GT + "/dev/null"}, self.root)
+        self._allow(out, c, "/dev/null is not an escape")
+
+
 if __name__ == "__main__":
     unittest.main()