@miller-tech/uap 1.184.0 → 1.184.1

package/docs/guides/POLICIES.md

@@ -191,3 +191,46 @@ uap policy convert --input <id|file.md> --output out.md   # render to CLAUDE.md
 
 Changes invalidate the gate's policy cache immediately, so they take effect on
 the next tool call.
+
+## Changing an enforcer's code
+
+Two things trip people up here, and both fail *silently* — the source looks
+fixed while the gate keeps enforcing the old behaviour.
+
+**1. The gate does not run `src/policies/enforcers/*.py`.** It runs
+`.policy-tools/<policyId>_<toolName>.py`, a separate materialized copy (plus a
+snapshot in the `code` column of `policies.db`). Editing the source changes
+nothing on its own — re-run `uap policy install <slug>` to refresh the
+executable copy:
+
+```bash
+uap policy install workdir-scope
+grep -l _my_new_function .policy-tools/*workdir_scope.py   # verify it took
+```
+
+**2. Run that install from the MAIN checkout, not a worktree.** The policy gate
+anchors runtime state — `policies.db` and `.policy-tools/` — to `MAIN_ROOT`, so
+that every worktree enforces the same policies. `uap policy install` run from
+inside a worktree gets this wrong in *both* directions, while still printing
+success:
+
+- it **reads** the enforcer source from the main checkout (not the worktree's
+  edited copy), and
+- it **writes** the materialized copy into a worktree-local `.policy-tools/`
+  that the gate never reads.
+
+So the install is a no-op for enforcement, and it is silent about it: the
+edited enforcer is verified by the test suite (which reads the worktree source)
+while the running gate still executes the old code. Verified 2026-08-03 by
+comparing the materialized copy against both sources — it matched the main
+checkout byte for byte.
+
+So an enforcer fix is two separate steps in two different directories:
+
+- edit the enforcer **in your worktree**, so the change ships in the PR;
+- after it merges, run `uap policy install <slug>` **from the main checkout** to
+  refresh the runtime copy.
+
+Note that `enforcement-self-protect` blocks agent writes to `src/policies/**`
+outright, with no model-reachable bypass. An agent cannot make either change —
+enforcer edits are an operator action by design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.184.0",
+  "version": "1.184.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",

package/src/policies/enforcers/codebase_read_before_plan.py

@@ -8,12 +8,41 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _common import arg_str, emit, parse_cli  # noqa: E402
+from _common import arg_str, emit, parse_cli, repo_root  # noqa: E402
 
 PLAN_OPS = {"ExitPlanMode", "Plan", "TodoWrite"}
 PLAN_WORD_RE = re.compile(r"(?<![-\w/])(plan the|design the|architect the|propose a plan|spec the)", re.I)
 READ_LOG = Path(os.environ.get("UAP_STATE_DIR", ".uap")) / "read_log.state"
 RECENT_SEC = 1800
+# The PostToolUse hook that writes READ_LOG. This gate accepts evidence that
+# ONLY that hook produces, so without it the evidence can never appear.
+#
+# Checked per platform, not just under .claude/: copyHookScripts() drops the
+# script into EVERY platform's hook dir, but each platform needs its own
+# PostToolUse wiring. A hardcoded .claude/ probe would report "writer present"
+# for a Factory or Cursor session whose settings never invoke it — enforcing
+# strictly against evidence that platform cannot produce, which is the same
+# permanent block this fail-open exists to prevent.
+WRITER_HOOK_DIRS = (".claude", ".factory", ".cursor", ".codex", ".forge", ".opencode")
+WRITER_HOOK_NAME = "post-tool-use-read.sh"
+
+
+def writer_installed() -> bool:
+    """True when the hook that populates READ_LOG is installed for this platform.
+
+    Load-bearing. For a long time nothing wrote read_log.state at all: the
+    matcher was never added to settings.json, the last entries aged past
+    RECENT_SEC, and this gate then refused every ExitPlanMode with a remedy
+    ("read the codebase first") that no amount of reading could clear. A gate
+    whose writer is missing silently escalates from advisory to a wall, so when
+    the writer is absent we degrade to advisory instead of bricking planning.
+    """
+    roots = (repo_root(), Path.cwd())
+    for root in roots:
+        for hook_dir in WRITER_HOOK_DIRS:
+            if (root / hook_dir / "hooks" / WRITER_HOOK_NAME).exists():
+                return True
+    return False
 
 
 def recent_reads() -> set[str]:
@@ -41,6 +70,9 @@ def main() -> None:
     if reads:
         emit(True, f"{len(reads)} recent codebase reads on record")
 
+    if not writer_installed():
+        emit(True, "read-log writer hook not installed — gate advisory (run `uap hooks install`)")
+
     emit(
         False,
         "codebase-read-before-plan: no Read/Grep/Glob within the last 30 min. "

package/src/policies/enforcers/expert_review_required.py

@@ -2,8 +2,9 @@
 """expert-review-required enforcer: a parallel expert review must precede ship.
 
 Blocks ship actions (git commit / git push / gh pr create / merge / pr-ready /
-signoff) unless a review artifact exists for the current branch AND covers the
-current HEAD. This makes the `parallel-expert-review` skill's "REQUIRED by
+signoff) unless a review artifact exists for the branch being shipped AND covers
+its HEAD. For `gh pr merge <N>` the branch being shipped is the PR's head
+branch, resolved via gh — not whatever branch the invoking shell is on. This makes the `parallel-expert-review` skill's "REQUIRED by
 policy" claim real rather than advisory.
 
 Review artifact: .uap/reviews/<branch-slug>.json, written by the
@@ -20,6 +21,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import shlex
 import sys
 from pathlib import Path
 
@@ -37,6 +39,19 @@ SHIP_PATTERNS = (
     re.compile(r"\b(pr[-_ ]?ready|sign[-_ ]?off|ready[-_ ]for[-_ ]review)\b", re.I),
 )
 
+# A ship action that NAMES a pull request. The review that matters is the one
+# for that PR's head branch, which is usually not the branch the shell is on.
+PR_SHIP_VERBS = ("merge", "ready")
+
+# Flags on those verbs that consume the NEXT token as their value. Without this,
+# `gh pr merge -b 1 900` reads "1" as the PR — so the review for PR 1 authorises
+# shipping PR 900. `gh pr merge --body Merging 123` misfires the same way by
+# accident, which is the more likely path to it happening.
+PR_VALUE_FLAGS = frozenset({
+    "-b", "--body", "-F", "--body-file", "-t", "--subject",
+    "-R", "--repo", "--match-head-commit", "-c", "--comment",
+})
+
 # Risk-scope: a parallel expert review is required only for *substantive* diffs.
 # A diff that touches ONLY low-risk surfaces (frontend/styles, docs, config,
 # tests, assets) ships freely — trivial/frontend PRs aren't gated. High-risk
@@ -115,6 +130,64 @@ def slug_for(branch: str) -> str:
     return branch.replace("%", "%25").replace("/", "%2F")
 
 
+def pr_reference(cmd: str) -> str | None:
+    """The pull request a `gh pr merge|ready` command names, or None.
+
+    Tokenized rather than pattern-matched on "digits right after the verb":
+    flags may come first (`gh pr merge --squash 645`), and gh accepts a number,
+    a URL, or a branch name interchangeably. The narrow form missed all of
+    those and fell back to the local branch — silently reinstating the very bug
+    this resolution exists to fix.
+
+    A bare `gh pr merge` (the current branch's PR) returns None, which is
+    correct: the local branch IS the right thing to check then.
+    """
+    try:
+        tokens = shlex.split(cmd, comments=True)
+    except ValueError:
+        return None
+    for i in range(len(tokens) - 2):
+        if (
+            os.path.basename(tokens[i]) == "gh"
+            and tokens[i + 1] == "pr"
+            and tokens[i + 2] in PR_SHIP_VERBS
+        ):
+            skip_value = False
+            for tok in tokens[i + 3:]:
+                if skip_value:
+                    skip_value = False
+                    continue
+                if tok.startswith("-"):
+                    # `--body=x` carries its value inline; `--body x` does not,
+                    # and that value can look exactly like a PR reference.
+                    if tok in PR_VALUE_FLAGS:
+                        skip_value = True
+                    continue
+                return tok
+            return None
+    return None
+
+
+def pr_target(root: Path, ref: str) -> tuple[str | None, str | None]:
+    """(head branch, head sha) of the PR being shipped, resolved via `gh`.
+
+    Returns (None, None) on any failure — no gh, no network, no auth, unknown
+    PR — so the caller falls back to the local branch and this stays fail-open.
+    `run` already bounds the call at 5s, and PR_SHIP_RE only matches an explicit
+    `gh pr merge/ready <N>`, so the cost is paid on ship actions, not per Bash.
+    """
+    rc, out, _ = run(
+        ["gh", "pr", "view", ref, "--json", "headRefName,headRefOid"], cwd=root
+    )
+    if rc != 0 or not out.strip():
+        return None, None
+    try:
+        data = json.loads(out)
+    except Exception:  # noqa: BLE001
+        return None, None
+    return (data.get("headRefName") or None), (data.get("headRefOid") or None)
+
+
 def head_sha(root: Path) -> str | None:
     rc, out, _ = run(["git", "rev-parse", "HEAD"], cwd=root)
     return out.strip() if rc == 0 and out.strip() else None
@@ -158,7 +231,16 @@ def main() -> None:
     # to MAIN_ROOT by the gate, so it always read the main checkout's branch and
     # demanded a review for the wrong branch on every worktree commit/push.
     root = worktree_root()
-    branch = current_branch(root)
+
+    # `gh pr merge 645` ships PR 645's branch. Reading the LOCAL branch here
+    # meant a merge run from the main checkout looked for .uap/reviews/master
+    # .json — an artifact for a branch that is not being shipped — and refused
+    # a PR whose own branch was reviewed and approved. Resolve the PR's head
+    # instead; fall back to the local branch when gh cannot answer.
+    pr_ref = pr_reference(cmd)
+    pr_branch, pr_sha = pr_target(root, pr_ref) if pr_ref else (None, None)
+
+    branch = pr_branch or current_branch(root)
     if branch is None:
         emit(True, "branch not resolvable (detached/non-git) — fail-open")
     slug = slug_for(branch)
@@ -172,7 +254,10 @@ def main() -> None:
     # migrations, or policy code — the change ships without a parallel review.
     # When the base diff is not resolvable (None) we do NOT skip: we can't prove
     # the change is low-risk, so the review requirement below still applies.
-    changed = _changed_files(root)
+    # Skipped for a PR ship: this diffs the LOCAL working tree, which on a
+    # `gh pr merge` from the main checkout is not the PR's contents at all —
+    # it would grade the wrong change as low-risk.
+    changed = None if pr_branch else _changed_files(root)
     if changed and all(_is_low_risk(f) for f in changed):
         emit(
             True,
@@ -191,7 +276,7 @@ def main() -> None:
             "(no longer honoured inline), or a waiver file.",
         )
 
-    head = head_sha(root)
+    head = pr_sha or head_sha(root)
     try:
         data = json.loads(review.read_text())
     except Exception:  # noqa: BLE001

package/src/policies/enforcers/memory_before_plan.py

@@ -8,16 +8,34 @@ import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
-from _common import arg_str, emit, parse_cli, repo_root  # noqa: E402
+from _common import arg_str, emit, parse_cli, repo_root, worktree_root  # noqa: E402
 
 PLAN_OPS = {"ExitPlanMode", "Plan", "TodoWrite", "plan", "design"}
 # Only match standalone words, not compounds like 'validate-plan-on-change'
 PLAN_WORD_RE = re.compile(r"(?<![-\w/])(plan the|design the|architect the|propose a plan|roadmap for)", re.I)
 RECENT_SEC = 300
+DB_REL = Path("agents") / "data" / "memory" / "short_term.db"
 
 
-def recent_memory_query(root: Path) -> bool:
-    db = root / "agents" / "data" / "memory" / "short_term.db"
+def candidate_dbs() -> list[Path]:
+    """Every short-term DB that could hold the evidence, worktree first.
+
+    `uap memory query` writes to the DB under the CWD, which inside a worktree
+    is the WORKTREE's DB — but this gate used to read only repo_root()'s. An
+    agent doing the required query while working in a worktree (which the
+    worktree policy mandates) therefore produced evidence the gate never saw,
+    and the remedy could not clear it. Same repo_root()-vs-worktree_root() bug
+    already fixed in expert-review-required and local-build-before-push.
+    """
+    seen: list[Path] = []
+    for root in (worktree_root(), repo_root()):
+        db = root / DB_REL
+        if db not in seen:
+            seen.append(db)
+    return seen
+
+
+def recent_memory_query(db: Path) -> bool:
     if not db.exists():
         return False
     try:
@@ -48,8 +66,9 @@ def main() -> None:
     if op not in PLAN_OPS and not PLAN_WORD_RE.search(blob):
         emit(True, "not a plan operation")
 
-    if recent_memory_query(repo_root()):
-        emit(True, "recent uap memory query on record")
+    for db in candidate_dbs():
+        if recent_memory_query(db):
+            emit(True, "recent uap memory query on record")
 
     emit(
         False,

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/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()