hooks: fire the self-match guard on a one-shot check too

[EdbertChan]

Summary

Follow-up to #323. That PR's detector stayed silent on a one-shot pgrep -f postgres, on the assumption it is a legitimate "is it running?" check.

Tested the assumption and it is wrong. The harness runs every tool call as bash -c '<the whole command>'.

So the pattern is already in a live cmdline before the search starts.

A bare pgrep -f for a token present on no process returned a pid and exit 0.

There is no correct plain -f spelling under such a harness. The one-shot answer is wrong too — just less loudly than a loop that never exits.

This makes the detector fire on the standalone and if-guarded forms as well, and rewrites the block message to explain the wrapper rather than only the loop.

Review Claim

Widening detector 3 from loop-shaped self-matches to every plain-literal -f pattern is correct rather than noisy, because under this harness the one-shot form is also a wrong answer — a true positive, not a tolerated false one.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

Behaviour change is strictly additive to what self_matching_process_waits already reported: no case that was silent for a good reason becomes noisy. The silent set is unchanged and still covered by fixtures — the bracket idiom, a name match without -f, a pattern held in a variable or command substitution, kill -0 "$PID", and a log-sentinel wait. The detector remains pure text analysis with no process lookup, no subprocess, and no file read, so widening it cannot make the hook itself slower or fallible at runtime. It stays inside pretooluse_problems(), whose only effect is stderr plus exit 2, and a detector exception is still trapped and reported as "allowing".

Assumptions: this Safety Invariant is unconfirmed — drafted under a non-interactive delegation with no user available to confirm it, per draft-pr's headless mode.

Slice Rationale

Separate PR because #323 was merged (squashed onto main as 6c7112b) while this commit was still local, so it could not ride along. Same three files, no new ones; the diff is the widening plus the fixture and README paragraph that justify it.

Non-goals

• Does not change the silent set. Every previously-allowed shape still has a passing negative fixture.
• Does not detect non-terminating waits in general, or resolve a variable pattern — both still out of scope and still passed through.
• Does not touch wait-needs-wakeup, which is what pushes agents into these loops.
• Does not rename the hook directory, still narrower than its scope; recommended as a follow-up and noted in the README.

Test Plan

Test Plan

Repro before:

• pgrep -f zzz_unique_token_ghwv_9931, a token on no process anywhere → printed pid 1766632, exit=0
• pgrep -af on the same token → the single match was /bin/bash -c source … — the harness's own wrapper carrying the command text
• main's detector (from hooks: refuse a process wait that matches its own command line #323) on pgrep -f postgres → silent, which is the gap this closes

Repro after — the five-probe set:

• the command that stranded the agent → fires
• bracket-trick form → silent
• log-sentinel form → silent
• pkill self-match → fires
• pgrep -f postgres → fires (was silent; this is the change)

Also fires: if pgrep -f nginx; then echo up; fi. Also still silent: pgrep run_all_tests.sh, pgrep -x bash, pkill -x node, kill -0 "$PID", pgrep -f "$PATTERN", a backtick-substituted pattern, ps aux | head -5.

Gates:

• python3 -m unittest discover -s engine/hooks/gh-write-verification/tests -v — 35 tests, OK
• bash scripts/run_all_tests.sh — 37 suites, EXIT6=0, no FAILED/ERROR: lines
• python3 scripts/check_hook_test_coverage.py engine/hooks/gh-write-verification — OK
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main — unit engine-runtime: 3 file(s), ok preflight passed
• python3 scripts/check_no_new_comments.py --base origin/main — ok no new comments
• python3 scripts/check_no_dated_provenance.py --base origin/main — ok no dated provenance
• ruff check . --select E9,F — All checks passed; shellcheck install.sh — clean
• node engine/skills/draft-pr/scripts/lint-diff-atomicity.mjs --base origin/main --review-lane behavior — passed, no warnings

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha>
• Post-revert steps: None. Reverting returns the detector to the loop-shaped behaviour merged in hooks: refuse a process wait that matches its own command line #323; no reinstall is needed because the hook's settings.json entries are unchanged.
• Data migration? No.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F43CBUnsDEs6J2zEC1r8a8

---

Note

Low Risk
Additive PreToolUse guidance and tests for gh-write-verification; no change to silent allowances and no runtime subprocess or I/O in the detector.

Overview
Clarifies and locks in the self_matching_process_waits guard so standalone and if-guarded pgrep -f / pkill -f with plain literals are treated as violations, not only loop-shaped waits.

The block message and README now explain the agent harness (bash -c '<command>'): the pattern is already on the wrapper’s cmdline, so a one-shot “is postgres running?” check can exit 0 even when the service is absent. Docs also note a sibling false-positive risk when detectors scan raw payload text (e.g. heredocs in tests).

New unit tests assert pgrep -f postgres and if pgrep -f nginx; then … are flagged. The silent set (bracket idiom, no -f, variables, kill -0, log sentinels) is unchanged per existing fixtures.

^{Reviewed by Cursor Bugbot for commit 45f2e49. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_f08fda23-bc43-440f-9ea3-c22cdf946389)

[mergify]

Queued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-09 21:45 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #324 on main (4b4677d) #326
• ✅ Merged — 2026-09-09 21:50 UTC · at 46e4b759c52f6a87f6a4187e76ad8afe6f6db29e · squash

This pull request spent 4 minutes 22 seconds in the queue, including 3 minutes 20 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test