Read the Guard's Token Fallback With a Bash-Aware Context Scan

[ptr727]

The write guard's shell-token fallback now reads a command with a bash-aware context scan. _context_lex replaces the comment strip and the _COMMENT_SCAN_BAIL skip list, so a quote, a substitution, a heredoc, or an arithmetic context spanning lines is read whole rather than cut at a line. _shell_tokens keeps develop's line reading followed by the scan's tokens, per #1960, so the scan only adds to what the guard judges. The wait rule judges both heredoc strips, _closes_as_arithmetic is linear, and _redirects_stdin refuses an operator as a redirect's target and reads a redirect with no target as no bound, per #2023. Every constructed example in #1910 is a selftest case.

One false deny is introduced and accepted per #2045: a quoted operator used as a redirect's target reaches the check bare, tracked in #2075.

#1910, #1958, and #1959 stay open, per #1960.

🤖 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: dea201b2-b9aa-4ef6-94c1-fb564219384b

---

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    #2076   +/-   ##
==========================================
  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 is a security-critical, fail-closed write guard whose new hand-rolled bash tokenizer carries intricate cross-context state and knowingly ships an accepted false-deny, so it warrants final human review.

Review effort: Balanced
Findings: None

What changed in this PR

This PR rewrites the shell-token fallback in the Claude Code write guard (gh-write-guard.py). When the primary shlex-based tokenizer cannot follow a command's quoting (for example an apostrophe in a trailing comment, or a quote nested inside "$(...)"), the guard previously stripped comments per whole command or tokenized each line in isolation, which lost quote/context state across lines and produced false denies. The new _context_lex scanner tracks the contexts bash actually nests (quotes, substitutions, $'...', arithmetic (( )), [[ =~ ]] operands, extglob patterns, and heredoc bodies) across line boundaries. Crucially, _shell_tokens keeps the old per-line reading and unions it with the scan's tokens, preserving the safety property that the fallback can only ever over-deny, never allow a command the prior fallback denied.

Changes:

• Add _context_lex and its helpers (_skip_group, _skip_nested, _skip_quote_body, _skip_backticks, _skip_heredoc_lines, _heredoc_bodies, _arith_depth, _paren_closers/_closes_as_arithmetic), and refactor _shell_tokens to return the union of _line_fallback_tokens and _context_lex.
• Harden the wait/redirect rules: _redirects_stdin now refuses a shell-operator token as a redirect target and treats a targetless redirect as binding nothing; _check_unbounded_wait and _heredoc_opener/_line_heredoc_opener/_heredoc_opener_in judge both the scan's and the line reading's heredoc stripping so a misread heredoc cannot hide a loop.
• Add extensive selftest coverage (_CONTEXT_LEX_CASES, new classify cases, and two linear-time performance assertions), keyed to the constructed examples from the referenced issues.

File	Description
host-setup/​agent-safety/​claude/​gh-write-guard.py	Replaces the guard's line-oriented comment-strip fallback with a bash-aware context scan unioned with the old reading, hardens redirect/heredoc/wait rules, and adds selftest cases.

---

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