Keep the Guard's Quote Mask When an Escape Sits Outside the Loop Condition

[ptr727]

Summary

The wait-loop rule's quote mask read no escapes, so a backslash anywhere in a command misaligned it, and a quoted ";" inside a bounded test was then read as a separator. That denied the three bounded loops in #1998.

• _marked_lex is an escape-aware lex that matches POSIX shlex token for token, and _quoted_mask now uses it.
• Wherever bash reads syntax that lex does not model, the mask falls back to the earlier quote-keeping mask (_quote_kept_mask, moved verbatim), so the verdict there equals develop's. That covers a backtick outside single quotes, $(/${ inside double quotes, $', a word-start #, and, per decision Decide How the #1998 Quote-Mask Fix Proceeds After Its Review Budget #2060, any command holding a << other than <<< and every loop inside a sh -c/bash -c payload, since a heredoc fed to a shell and a payload are each read twice.
• Self-test rows: the three Wait-Loop Bound Check Drops Its Quote Mask on Any Escape in the Command #1998 repros and a '\'' case are allowed and fail with the fix reverted, and eight deny rows pin every fail-open shape the local reviews found, each confirmed to loop under bash.

Verification

• gh-write-guard.py --selftest passes. Reverting either new fallback fails its own row.
• ruff format, ruff check, mypy, the prose gate, and the eol gate are clean.
• A differential verdict fuzz against develop found no heredoc or shell-payload command whose verdict differs. The top-level flips it found are the Wait-Loop Bound Check Drops Its Quote Mask on Any Escape in the Command #1998 direction, and bash evidence places the ones that still loop in the pre-existing The Wait-Loop Bound Check Counts a Comparison Bash Never Evaluates #2058 class.
• Local strict review: three recorded passes, the last with no finding against this change.

Pre-existing defects found along the way are filed as #2058, #2059, #2080, and a comment on #2064.

Closes on promotion: #1998

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: ptr727/ProjectTemplate/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 40433eb7-fb97-47f8-bf0a-f1c6139ff36d

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (develop@b56efb2). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #2081   +/-   ##
==========================================
  Coverage           ?   55.91%           
==========================================
  Files              ?       16           
  Lines              ?     7359           
  Branches           ?        0           
==========================================
  Hits               ?     4115           
  Misses             ?     3244           
  Partials           ?        0           

Flag	Coverage Δ
python-3.13	55.91% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It reworks the core lexing logic of a security-sensitive write-safety guard where a subtle fail-open would be high-impact, so it warrants final human review despite the extensive verification.

Review effort: Balanced
Findings: None

What changed in this PR

This PR fixes a false-deny regression in the agent write-safety guard (gh-write-guard.py, requirement 7, the unbounded-wait-loop rule). Previously, the quote mask that lets the guard tell a quoted operand (e.g. ";") from a real separator was recovered by a second lex that read no escapes, so any backslash anywhere in a command misaligned the mask and dropped it for every loop, wrongly denying three bounded loops. The change introduces an escape-aware lexer that reproduces the POSIX shlex token stream while tracking per-token quoting, and falls back to the prior escape-blind mask wherever bash reads syntax that shlex does not model, preserving develop's verdict on those shapes.

Changes:

• Add _marked_lex (escape-aware tokenizer with a marked flag) plus the _UnmodeledSyntax sentinel; rewrite _quoted_mask to use it and factor the old escape-blind mask into _quote_kept_mask.
• Fall back to the quote-kept mask for unmodeled syntax (backtick, $(/${ inside double quotes, $'…', word-start #, any << heredoc) and for recursion into sh -c/bash -c payloads that the outer lex already unescaped.
• Add 12 self-test rows: the three issue repros and a '\'' case (allow), plus eight deny rows pinning fail-open shapes surfaced during review.

File	Description
host-setup/​agent-safety/​claude/​gh-write-guard.py	Adds escape-aware _marked_lex/_UnmodeledSyntax, reworks the quote-mask helpers, gates the payload mask by recursion depth, and pins the new behavior with self-test rows.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.