hooks: refuse a process wait that matches its own command line

[EdbertChan]

Summary

Fourth detector for gh-write-verification, following #322. Same class as the other three: a command that silently reports the wrong thing.

pgrep -f and pkill -f compare full command lines. The pattern sits in the argv of the shell that runs them, so the match is never empty.

A wait negated on pgrep -f <name> can therefore never exit. pkill -f <name> kills its own wrapper mid-command.

One agent armed three such waits, ended its turn expecting to be woken, and was never resumed. Two were still spinning 45 minutes later.

The trap is baited by this repo: wait-needs-wakeup blocks a plain foreground wait and tells you to arm a watcher, without saying how to write one that terminates.

It fires on a one-shot check too. 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.

pgrep -f postgres therefore exits 0 whether or not postgres runs anywhere. There is no correct plain -f spelling here.

Review Claim

A PreToolUse detector that decides, from the command text alone, whether a pgrep/pkill full-command-line match will also match the shell issuing it — firing on every plain-literal -f form, looped or one-shot, and on a bracket class undone by a plain mention elsewhere, and staying silent on the bracket idiom, a name-only match, a variable pattern, and a log-sentinel wait.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The detector is pure text analysis: it runs no process lookup, spawns nothing, and reads no file. It reaches a verdict only from the command string already in the hook payload, so it cannot itself be fooled by the live process table it is reasoning about. It is wired into the existing pretooluse_problems() list, which already writes to stderr and exits 2 and has no other write path; a detector exception is trapped by claude_pretooluse.py and reported as "allowing", so a bug can only under-block. A pattern held in a variable or command substitution is deliberately passed through rather than guessed at.

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 #322 was merged (squashed onto main as e8fbb71) while this commit was still local, so it could not ride along. It is additive to the same hook: one new detector function, its message, its fixtures, and a README section. No existing detector changes.

Non-goals

• Does not change wait-needs-wakeup, which is what pushes agents into these loops. This only makes a loop terminate; whether the loop should exist stays that hook's call. Expect both to fire on the same command.
• Does not detect a non-terminating wait in general — only the self-match. A loop waiting on a condition that never becomes true for some other reason is out of scope.
• Does not exempt a one-shot pgrep -f <service>. Reviewed and kept firing: under a harness that wraps each call in bash -c '<the whole command>', that check is contaminated too — it returns the wrapper and exits 0 for a service running nowhere — so it is a true positive, not a tolerated false one. Narrowing to until/while loops would also miss a one-shot pkill -f and an if pgrep -f X; then guard. The fixture carries this reasoning in its docstring so it is not later relaxed to silent.
• Does not resolve a pattern held in a variable or command substitution. Undecidable from the text, so it passes through; this under-blocks by design.
• Does not kill or inspect any running process.
• Does not rename the hook directory, though gh-write-verification is now narrower than its scope — this detector is not a gh write. Renaming would rewrite every file plus the install.sh wiring and the settings marker; recommended as a follow-up and noted in the README.

Test Plan

Test Plan

Repro before:

• pgrep -f zzz_selfmatch_demo_ghwv.sh for a token no process on this box uses → RUNNING; pgrep -af on the same token showed it matched the argv of the shell asking the question
• a token appearing exactly once, as the pgrep argument only → still RUNNING. So a check for "the pattern appears elsewhere in the command" would miss the canonical loop, which names the process once — the detector fires on the plain-literal form instead
• bare one-shot pgrep -f zzz_unique_token_ghwv_9931, a token on no process anywhere → printed a pid and exit=0; pgrep -af showed the match was the harness's own bash -c wrapper. This is why the one-shot case fires
• pkill -f vvvv_selfkill_ghwv inside bash -c → the following echo SURVIVED never ran; the wrapper was killed, harness reported exit 144
• live stuck watcher on this box, PID 1429941: its log sentinel had already matched 35 times, so only the ! pgrep half kept it alive. Killed; ps -p confirmed gone
• bracket form in isolation → absent; the same bracket form in a command that also spells the token plainly → RUNNING, which is why the detector re-checks for a plain mention

Repro after — fires:

• the incident wait loop, pkill -f run_all_tests.sh, pgrep -af my_worker.py, pgrep --full …, pgrep -f -u edbert …, a bracket pattern undone by a plain mention in the same command, plus the one-shot pgrep -f postgres and if pgrep -f nginx; then …
• entrypoint returns exit 2 with the message naming kill -0 and the log-sentinel shape

Repro after — stays silent:

• bracket idiom alone; a log-sentinel wait; pgrep run_all_tests.sh / pgrep -x bash / pkill -x node (no -f); 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, EXIT5=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. The detector is additive; reverting leaves the three detectors from hooks: refuse a write whose effect you cannot see #322 wired and working, and no reinstall is needed because the hook's settings.json entries are unchanged.
• Data migration? No.

Sibling defect worth naming

Three hooks in this repo, including this one, share a failure shape: a scanner that reads data as code.

wait-needs-wakeup blocks on until/sleep appearing anywhere in a payload — it fired twice today on test strings being handed to a detector, not on commands being run, and blocked authoring work on this very PR. no-comments had the same shape until triple-quoted strings were excluded from its scan (#303), and it still misreads a ## markdown heading inside a Python string. This detector is exposed too: it matches patterns in raw payload text, so documenting it in an inline heredoc trips it, which the README records.

Not fixed here — named so the class is visible rather than rediscovered a fourth time.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F43CBUnsDEs6J2zEC1r8a8

[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_b3051198-9102-465d-982c-569413fdc815)