Fail Closed on Words the Shell Rewrites Before Git Reads Them in the Write Guard

[ptr727]

Summary

This closes the write guard's gaps where the shell rewrites or drops a word before git reads it, in host-setup/agent-safety/claude/gh-write-guard.py, and names pr_review.py cleanup in the managed permission rule's description. Each guard fix adds a reading or a deny beside develop's and replaces none of develop's readings.

• Quote-split words and uppercase GIT (Read Words the Shell Rewrites Before a Push in the Write Guard #2959). The push and include pre-filters also read each command with its quotes and backslashes removed, with git matched without case. So git p''ush origin develop, git "pu"sh ..., git p\ush ..., git -c 'inc''lude.path=/example/config' p, and GIT push ... reach the existing push and include checks, which already read the joined tokens. The same widened match is used inside _unreadable_push for eval, wrapper, -c, and command-running arguments.
• Run-time words (Read Words the Shell Rewrites Before a Push in the Write Guard #2959, Fail Closed on a Comment or a Substitution in a Push or Commit's Own Words in the Write Guard #2961). A new deny, _rewritten_git_words, fails closed rather than modeling the expansion. A run-time word is a $, a backtick, a brace expansion, or a lone parenthesis run from $(. It denies:
  • a run-time word where any git command's subcommand goes, which covers a backtick word ending the global options, as in git -c core.hooksPath=/dev/null `true` commit
  • a run-time global option word that word splitting may split, on any git command, or before no subcommand word at all
  • any run-time word among a push's or a commit's global options other than a directory option's value
  • a run-time word among a push's arguments, as in git push origin $(echo develop) or "$B"
  • a run-time word among a commit's arguments, other than a commit option's value whose expansions sit inside double quotes, or a path after --
  • a redirection where the subcommand goes or among the global options, unless git's first word is a terminal option such as --version, and a redirection target spanning several words on a push or commit, since the push and bypass readings stop at its parenthesis
• Comments (Fail Closed on a Comment or a Substitution in a Push or Commit's Own Words in the Write Guard #2961). An unquoted comment among a push's words denies, so git push # feature/y on a develop checkout is no longer read as an explicit push of feature/y. A comment on a commit only adds words the guard reads, which can only add a deny, so it is left alone.
• The managed permission rule (Name the cleanup Subcommand in the Managed pr_review.py Allow Rule's Description #2968). The comment above MANAGED_PERMISSIONS and the Claude kit README name cleanup beside reply, and say every check for the delete lives inside the subcommand because the :* rule approves any arguments. No behavior changes in install.py.

Only a git word in a command's position counts, so grep -rn git "$W" is no git command, and a git word after an unquoted ( counts, so <(git ...) is read. The common agent shapes still allow: a heredoc -m "$(cat <<'EOF' ...)" message (with apostrophes, backticks, braces, or one unbalanced double quote in its body), -m "$MSG", --author="$A", git -C "$W" push origin feature/x, unquoted git -C $W commit/push, and git -C "$W" log/status/diff.

Requirement 4 in host-setup/agent-safety/README.md and the guard bullet in the Claude kit README state the new denies.

Differential Against Develop's Guard

Develop's guard (the merge base, e98def1) and this branch's guard were loaded side by side and run over the same calls.

• Corpus: 18,393 constructed commands. They cross 35 heads with 8 mutation families and 12 wrappers. The heads are 18 push forms, 9 commit forms including two heredoc messages, and 8 other git commands. The mutation families are quote splits of push/commit/include/git/develop (uppercase and mixed-case git among them), run-time refspecs ($(...), backtick, $B, "$B", ${B}, $'...', an empty expansion, a substitution holding a ;), run-time subcommands, run-time global options (-c "$X", `true`, $(true), -C "$W", -C $W, -C $(pwd), --git-dir=, --work-tree=, $OPTS), comments, run-time commit arguments, and redirections. The wrappers are plain, bash -c, sh -c ... _ develop, eval quoted and unquoted, a leading cd, &&, ;, timeout, a subshell, x=$(...), and grep -rn. Sixteen shapes the issues name are added whole.
• Real-repository mode: each command in a constructed repository's develop checkout and in worktrees on feature/example, release/1.0, and x/develop, each with a real upstream, under six rule sets, one protecting only the stripped names 1.0 and example. That is 441,432 calls per guard with no current-branch seam.
• Seam mode: the same corpus under 6 current-branch seams and 4 rule seams (441,432 calls).
• Self-test replay: every classify call the branch self-test makes (894), with each pinned command list mirrored into develop's module.
• Rule 6: the corpus with a primary-checkout lookup (18,393 calls).

Allow flips (develop denies, this branch allows): zero in every mode. Crashes: zero.

Every deny flip, by the reason the branch gives, from real-repository mode's 7,303 distinct flipped commands:

• 2,721: a run-time word where the subcommand goes (git $S, git $(echo push), git `true` commit, git -C $(pwd) status).
• 1,485: a quote-split or uppercase push now read by the existing push check, denied as a pull-request, force, delete, or unresolved-branch push.
• 1,424: a run-time push argument.
• 764: a comment among a push's words.
• 320: a run-time commit argument ("$F" before --, -m $M, $(echo --no-verify), --author=$A).
• 237: a quote-split push or include key now read inside an eval or wrapper argument, or under an include override.
• 180: a redirection target spanning several words (2>$(mktemp)).
• 170: a run-time global option word on a push or commit (-c "$X", -c user.email=$E).
• 2: a quote-split push inside an inline alias value or a rebase --exec argument.

Seam mode gives the same classes over 7,561 distinct commands. Rule 6 gives 3,009, the same classes less those rule 6 already denies on develop. The self-test replay flips are exactly the 37 new discriminating cases. Each new deny case fails against develop's guard, which _GIT_CASES run against develop's module confirms. On long commands the branch costs about 1.4s more on a 3,000-line heredoc commit (5.5s against 4.0s) and about 1.2s more on 2,000 chained git -C "$W" status commands.

Known New Over-Denials

• Any run-time push refspec or remote, such as git push origin "$B" or "$(git branch --show-current)".
• Any run-time word where a git command's subcommand goes, on any command, such as git $S, git "$@", and git -C $(pwd) status.
• An unquoted run-time global option value that may split, such as git -C $W with no subcommand word, or git --namespace $X log. Any run-time global option on a push or commit other than a directory value, such as git -c user.email="$E" commit.
• An unquoted run-time commit argument, such as -m $MSG, --author=$A, or -m $(cat file), and a quoted one before -- that no option takes, such as git commit -m x "$F".
• Any comment among a push's words, such as git push origin feature/x # note.
• A redirection target spanning several words on a push or commit, such as 2>$(mktemp).
• A redirection before the subcommand, such as git 2>/dev/null status, unless git's first word is a terminal option such as --version.
• A -m value whose quote-keeping token cannot be read, other than one closed "$(...)" word, when some other part of the command breaks that token reading.

Left Open Deliberately

• An unquoted directory value that word splitting splits into more options, as in X='. -c core.hooksPath=/dev/null'; git -C $X commit, stays read as it stands, since an unquoted git -C $W commit is a common agent spelling. Filed as Decide Whether an Unquoted Directory Option Value Fails Closed in the Write Guard #2977. A brace expansion in a directory value denies.
• A git word the guard never sees as git, a backtick-opened `git push ...` or a run-time command word G=git; $G push, is filed as Read a Backtick-Opened or Run-Time Git Command Word in the Write Guard #2976.
• An abbreviated --no-verify, as in git commit --no-veri, is outside this class and filed as Read an Abbreviated --no-verify on a Commit or Push in the Write Guard #2978.

Local Review

Eight local strict-review passes ran at the frontier tier, each recorded. None found an allow flip against develop. Each of the first five found gaps in this change's own fix, fixed in the commits after the first:

• a quoted part before an unquoted expansion in a commit value
• a run-time option value supplying the subcommand, on any git command
• abbreviated value options taking -- as their value
• brace expansion, quoted parts inside a brace included
• a multi-token redirection target, and a redirection where the subcommand goes or among the global options, numbered and {name} forms included
• a terminal option such as --version exempting a redirection, now only as git's first word, which also clears the git --version >/dev/null 2>&1 over-deny an earlier commit introduced

The sixth pass raised one deny-reason wording mismatch, fixed in a commit the seventh pass confirmed changes that string alone. The eighth pass covered the fix for Copilot's quoted-operator finding and found no open issue. Declined:

• Sharing _opaque_cd's run-time predicate would replace a develop reading, since its exclusions differ.
• git -C "$W" --version >/dev/null denies, since the terminal-option exception holds only as git's first word. Agents write git --version first, so it is a stated over-deny.
• Sentence-length findings are declined as style, since that check is in no gate.

No local finding is open.

Verification

• gh-write-guard.py --selftest: SELFTEST PASS, 37 new discriminating cases and 12 new controls.
• ruff check, ruff format --check, mypy, python3 -m unittest discover -s tests, spec/audit.py --selftest, test_install.py, build_dist.py --check, repo_gate.py (default, eol, eol-coverage), prose_lint.py on the changed files and --diff against the merge base, spec/validate.py, and docker_lint.py all pass. The only prose finding is comment-added, for the install.py comment Name the cleanup Subcommand in the Managed pr_review.py Allow Rule's Description #2968 asks for and one classify comment, so this pull request carries the comments label.

After merge, the host-safety installer payload changes. The installer is not run here, and the maintainer runs it after promotion.

Closes #2959
Closes #2961
Closes #2968

🤖 Generated with Claude Code

[ptr727]

A recorded local strict-review pass covers head 6d6ddb6a97879d4d6b528c423d6f81b88b6c6c14, the content this pull request carries at that commit against develop, and it recorded 1 finding.

[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: f169edce-441d-4cb1-84bd-9c0f749fdc70

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

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #2979   +/-   ##
==========================================
  Coverage           ?   60.53%           
==========================================
  Files              ?       17           
  Lines              ?     8904           
  Branches           ?        0           
==========================================
  Hits               ?     5390           
  Misses             ?     3514           
  Partials           ?        0           

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

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]

🟡 Changes recommended

Unresolved critical and moderate guard correctness issues block approval.

2 open findings

• Preserve quote information when finding command end · New
• Reject redirections used as global-option values · New

What changed in this PR

This PR hardens the Git write guard against shell-rewritten words and updates managed permission documentation.

Changes:

• Adds detection for runtime expansions, comments, redirections, and quote-split Git commands.
• Expands safety documentation and self-tests.
• Documents pr_review.py cleanup permission coverage.

Unresolved review findings remain in gh-write-guard.py: two critical P1 issues and three moderate P2 issues.

File	Description
host-setup/​agent-safety/​README.md	Documents new guard behavior.
host-setup/​agent-safety/​claude/​README.md	Updates safety and permission documentation.
host-setup/​agent-safety/​claude/​install.py	Documents cleanup permission coverage.
host-setup/​agent-safety/​claude/​gh-write-guard.py	Implements shell-rewrite detection and self-tests.

🧠 Review effort: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ptr727]

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

[ptr727]

A recorded local strict-review pass covers head a95015be75d554051e5396e55a5b6f76ef9e4c91, the content this pull request carries at that commit against develop, and it recorded 1 finding.

[Copilot]

🟡 Changes recommended

Unresolved guard issues include a critical command-substitution inspection gap.

1 open finding

• Inspect quoted command-substitution bodies recursively · New

2 resolved since last review

• Reject redirections used as global-option values
• Preserve quote information when finding command end

🧠 Review effort: Lite