[ptr727]

Summary

Narrows the write guard's backslash-newline denies, which since the last round read every backslash-newline in a command naming git or gh, quoting and heredoc data included.

• A scan, _line_break_contexts, maps each backslash-newline to its context.
• Unquoted, inside double quotes, in an unquoted heredoc, at a comment's end, and wherever the scan does not finish, the split-word and escaped-line-break denies stand as before.
• A single unquoted backslash-newline between a command separator (&&, ||, |, |&, ;, &) and a non-operator character splits no word, so it is left to the fold.
• Inside single quotes, or ending a quoted heredoc data line not followed by its delimiter, the outer shell keeps the backslash-newline as text. _literal_span_kept keeps such a span as text only where the hook can read it as a shell running it would. A single-quoted span must be its word's only quoted, escaped, or expanded part. A span naming git, gh, or a push must hold no further quoting, with each backslash-newline in its own command text or ending a comment there. A span not kept is read as develop reads it.
• For a kept span, the command is classified again with each backslash-newline as the span's own scan places it, with each joined, and with each a line break, and denied where any reading is.
• The README's requirement 4 paragraph describes the cases the denies skip.

Refs #3344. This fixes these items from #3344:

• "Over-Denials the Change Introduces": all three, a single-quoted backslash-newline, a Markdown hard line break in a quoted heredoc inside "$(cat <<'EOF' ... EOF)", and git commit -F- <<'EOF' data ending in \.
• The fourth-pass item on _SPLIT_WORD matching an operator glued to a line continuation, git add x &&\ and git log --oneline |\.

The other items in #3344 are not addressed here.

Verification

• Self-test passes. New cases cover each intended allow and a deny for each shape that must still deny: a split inside double quotes, in an unquoted heredoc, before a quoted heredoc's delimiter, inside $'...', an &\-newline-& split operator, a redirection operator, single-quoted shell bodies (joined, escaped backslash, comment-ending, mixed comment-ending and splitting), quoted heredocs fed to a shell, a further quoting level, a '\''-joined word, and a span after an escaped word break.
• Revert proofs: with the narrowing replaced by develop's whole-text regexes, the new allow cases fail. With no extra readings, the six shell-body deny cases fail. With the line-break reading removed, the two comment-ending cases fail. With only the joined and line-break readings, the three mixed cases fail. With every span kept, the nesting and word-adjacency cases fail.
• Differential: every distinct command string the self-test and test_install.py pass to classify, plus constructed probes from this lane and its local review passes, classified under develop's guard and this branch's with identical offline seams. 10560 distinct commands: 3889 deny/deny, 6591 allow/allow, 78 deny to allow, 2 allow to deny, 0 errors.
  • The recorded self-test and test_install.py corpus flips only on this branch's seven new allow cases.
  • Every probe-only deny-to-allow flip is an intended form or a direct sibling (single-quoted data, quoted-heredoc data including Markdown bodies with apostrophes, a continuation glued to a separator), or a command whose plain form develop already allows (filed below, or harmless, such as a ref holding a backslash or a word with a plain suffix).
  • The two allow-to-deny flips are a spaced comment-ending backslash-newline in a bash -c body, which develop allowed while denying its plain form.
• test_install.py, prose_lint.py (diff scope, sentence-length included), repo_gate.py --check eol and eol-coverage, spec/validate.py, ruff, and the markdownlint, cspell, and editorconfig-checker Docker linters are clean.

Known Remaining Findings

The local review reached its cap of six passes. The last two passes stopped before probing, so their probe phase ran in the lane itself over the separator and kept-span paths, with no new flip. These introduced findings remain, each a wording or over-deny item rather than an allow. Each is filed in #3358, since a fix push would need a pass past the cap:

• introduced, docs: the README states the word rule as "its word's only quoted part", where the code also refuses an escaped or expanded part, and states the names test as "git or gh", where the code also tests a push in each reading.
• introduced, docs: _literal_span_kept's summary line reads as if every kept span is read as its inner scan places it, which its later lines qualify for a span naming no git or gh.
• introduced, over-deny: for an escaped backslash before a kept newline, every reading drops the backslash pairs, where a shell keeps one literal backslash per pair. This can only make a reading deny more.
• introduced, residual over-deny: a quoted span naming git or gh that also holds an apostrophe, double quote, backquote, or << is read as develop reads it. A Markdown PR body mentioning git in a code span and holding a hard line break is still denied, as on develop.

Filed

Pre-existing gaps the local review found, each allowed on develop in its plain form: #3351 (a cd that does not lead the command, for rule 6), #3352 (a trap action string), #3353 ()# and <<- tab stripping), #3355 (a comment-ending backslash-newline at top level, and an eval body, for rule 6), #3356 (text piped into a shell, or produced by $(...) as a -c body). Design: #3354 (consolidate the guard's context scanners).

#3341 Confirmation

BASH_BIN="$(command -v bash)"; git push --tags origin and bash -c 'command -v sh'; git push --tags origin both classify allow on develop 201cbe7 with offline seams.

🤖 Generated with Claude Code

[ptr727]

A recorded local strict-review pass covers head 9d5cfe3dcfa17dbb580a9913d2a86466beacd491, the content this pull request carries at that commit against develop, and it recorded 3 findings.

[coderabbitai]

Important

• 🔍 Trigger review

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

⚙️ Run configuration

• Source mode: Auto
• Repository: ptr727/ProjectTemplate
• Branch: feature/guard-backslash-newline-quoting
• File: .coderabbit.yaml
• Commit: 494a690
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2e2c66b5-8f71-40ef-9c7b-cd05d13b3ec7

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[Copilot]

🟡 Changes recommended

The guard can allow a command when an inner shell mixes continuation readings, and the README needs clarification.

2 open issues

• Model literal continuations independently in nested shell parsing · New
• Correct documentation for command substitution and ANSI-C quoting · New

What changed in this PR

This pull request narrows write-guard denials for backslash-newlines by recognizing shell quoting, heredocs, comments, separators, and nested shell readings.

Changes:

• Adds context-aware scanning and alternate backslash-newline readings.
• Recursively reclassifies quoted heredoc and nested shell-body content.
• Updates the safety README and expands regression coverage.

File	Reviewed changes
host-setup/​agent-safety/​README.md	Documents the revised quoting and heredoc behavior. Nit (P2): Clarify command-substitution and ANSI-C exceptions to match the scanner.
host-setup/​agent-safety/​claude/​gh-write-guard.py	Implements contextual scanning, recursive readings, and regression tests. Critical (P1): Preserve independent inner-shell readings for each literal continuation.

_{Review effort: Lite}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.32%. Comparing base (201cbe7) to head (494a690).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #3357       +/-   ##
============================================
+ Coverage    65.53%   81.32%   +15.78%     
============================================
  Files           18       18               
  Lines        10036    10045        +9     
============================================
+ Hits          6577     8169     +1592     
+ Misses        3459     1876     -1583     

Flag	Coverage Δ
python-3.13	81.32% <ø> (+15.78%)	⬆️

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.

[ptr727]

A recorded local strict-review pass covers head 494a6908bfacb84f77fcf6f8021975a3ed7d547b, the content this pull request carries at that commit against develop, and it recorded 5 findings.