Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/hook-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,6 @@ jobs:
env:
TEST_REPO_DIR: ${{ github.workspace }}
run: bash global-settings/tests/test-block-write-commands.sh

- name: Run no-polling hook tests
run: bash global-settings/tests/test-block-polling.sh
2 changes: 2 additions & 0 deletions global-settings/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Current version: see [`VERSION`](VERSION)
| ----------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `settings.json` | `~/.claude/settings.json` | Permissions allowlist + hooks |
| `block-write-commands.sh` | `~/.claude/hooks/block-write-commands.sh` | Guards Bash write operations, prompts for approval |
| `block-polling.sh` | `~/.claude/hooks/block-polling.sh` | Blocks hand-rolled waiting: CI watch commands, poll loops, long sleeps, idle heartbeats (velocity plan item 5, 2026-09-12) |
| `block-config-tool-writes.sh` | `~/.claude/hooks/block-config-tool-writes.sh` | Guards Write/Edit/MultiEdit calls — denies tools that write to `~/.claude/` or produce scripts that would (added in v1.7.0) |
| `check-settings-version.sh` | `~/.claude/hooks/check-settings-version.sh` | Warns at session start if settings are outdated |
| `sound-notify.sh` | `~/.claude/hooks/sound-notify.sh` | Optional notification-sound wrapper. Reads `~/.claude/sound-config.sh` and plays a sound on question / permission / stop events. Silent by default (added in v2.2.0) |
Expand All @@ -31,6 +32,7 @@ mkdir -p ~/.claude/hooks

cp "$REPO_ROOT/global-settings/settings.json" ~/.claude/settings.json
cp "$REPO_ROOT/global-settings/block-write-commands.sh" ~/.claude/hooks/block-write-commands.sh
cp "$REPO_ROOT/global-settings/block-polling.sh" ~/.claude/hooks/block-polling.sh
cp "$REPO_ROOT/global-settings/block-config-tool-writes.sh" ~/.claude/hooks/block-config-tool-writes.sh
cp "$REPO_ROOT/global-settings/check-settings-version.sh" ~/.claude/hooks/check-settings-version.sh
cp "$REPO_ROOT/global-settings/sound-notify.sh" ~/.claude/hooks/sound-notify.sh
Expand Down
2 changes: 1 addition & 1 deletion global-settings/VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.4.6
2.5.0
54 changes: 54 additions & 0 deletions global-settings/block-polling.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
#!/usr/bin/env bash
# PreToolUse(Bash) guard: block hand-rolled waiting.
#
# Why: the 2026-09-12 velocity diagnosis counted 2,043 `echo idle`, 929 `true`,
# 453 `cd … && echo waiting`, 395 streaks of five or more consecutive CI polls
# and 35.7 hours of sleep loops in twelve days of sessions. A session that waits
# by hand burns turns and context; a session that pushes and moves on does not.
#
# Blocks, per command segment:
# - `gh run watch`, `gh pr checks --watch` (CI is the arbiter, not the loop)
# - `while|until … sleep` (a poll loop in one command)
# - `sleep N` with N >= 60 (a long wait)
# - `echo idle`, `echo waiting`, `tail -f /dev/null`, `timeout N tail -f`
# Allows: short `sleep` (< 60 s) for a service to come up, `gh run view`,
# `gh pr checks` without --watch (one read is fine), everything else.
#
# What to do instead: push and continue with the next task; use the Monitor
# tool or a background command with an `until` condition when a later event
# genuinely matters; read CI once, at the end, if at all.
set -uo pipefail
input="$(cat 2>/dev/null || true)"
cmd="$(printf '%s' "$input" | python3 -c 'import sys,json
try: print(json.load(sys.stdin).get("tool_input",{}).get("command",""))
except Exception: print("")' 2>/dev/null || true)"
[ -z "$cmd" ] && exit 0
deny() { printf 'BLOCKED by the no-polling guard: %s\nPush and move on. For a later event use the Monitor tool or a background command with an until-condition. Read CI once, at the end.\n' "$1" >&2; exit 2; }

# whole-command shapes first (a loop spans segments)
if printf '%s' "$cmd" | grep -qE '(^|[[:space:];&|(])(while|until)[[:space:]].*sleep[[:space:]]'; then
deny "a while/until … sleep loop is a poll loop."
fi

segments="$(printf '%s' "$cmd" | sed -E 's/(\|\||&&|[;&|])/\n/g')"
while IFS= read -r seg; do
[ -z "$seg" ] && continue
if printf '%s' "$seg" | grep -qE '(^|[[:space:]])gh[[:space:]]+run[[:space:]]+watch([[:space:]]|$)'; then
deny "gh run watch waits on the CI queue (96% of CI wall-clock is queueing)."
fi
if printf '%s' "$seg" | grep -qE '(^|[[:space:]])gh[[:space:]]+pr[[:space:]]+checks[^|;&]*--watch'; then
deny "gh pr checks --watch waits on the CI queue."
fi
if printf '%s' "$seg" | grep -qE '(^|[[:space:]])sleep[[:space:]]+([6-9][0-9]|[1-9][0-9]{2,})([[:space:]]|$)'; then
deny "sleep of 60 s or more is a hand-rolled wait."
fi
if printf '%s' "$seg" | grep -qE '(^|[[:space:]])echo[[:space:]]+"?(idle|waiting)"?([[:space:]]|$)'; then
deny "echo idle / echo waiting is a heartbeat for a wait loop."
fi
if printf '%s' "$seg" | grep -qE 'tail[[:space:]]+-f[[:space:]]+/dev/null'; then
deny "tail -f /dev/null is a sleep in disguise."
fi
done <<EOF
$segments
EOF
exit 0
24 changes: 9 additions & 15 deletions global-settings/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
"Edit(~/.claude/settings-repo-url)",
"Edit(~/.claude/settings-repo-ref)",
"Edit(~/.claude/user-hooks.json)",

"Bash(sudo:*)",
"Bash(su:*)",
"Bash(shutdown:*)",
Expand All @@ -17,11 +16,9 @@
"Bash(poweroff:*)",
"Bash(mkfs:*)",
"Bash(dd if=:*)",

"Bash(gh pr merge:*)",
"Bash(gh repo delete:*)",
"Bash(gh release delete:*)",

"Bash(git reset --hard:*)",
"Bash(git clean -f:*)",
"Bash(git clean -fd:*)",
Expand All @@ -37,10 +34,8 @@
"Bash(git push --force:*)",
"Bash(git push -f:*)",
"Bash(git rebase:*)",

"Bash(rm -rf:*)",
"Bash(rm -Rf:*)",

"Bash(pip install:*)"
],
"allow": [
Expand All @@ -59,7 +54,6 @@
"Bash(realpath:*)",
"Bash(basename:*)",
"Bash(dirname:*)",

"Bash(diff:*)",
"Bash(grep:*)",
"Bash(egrep:*)",
Expand All @@ -69,7 +63,6 @@
"Bash(cut:*)",
"Bash(uniq:*)",
"Bash(column:*)",

"Bash(which:*)",
"Bash(whoami:*)",
"Bash(uname:*)",
Expand All @@ -83,7 +76,6 @@
"Bash(hostname:*)",
"Bash(env:*)",
"Bash(date:*)",

"Bash(git log:*)",
"Bash(git status:*)",
"Bash(git diff:*)",
Expand All @@ -105,9 +97,7 @@
"Bash(git stash show:*)",
"Bash(git config --list:*)",
"Bash(git config --get:*)",

"Bash(cd:*)",

"Bash(docker ps:*)",
"Bash(docker image inspect:*)",
"Bash(docker images:*)",
Expand All @@ -124,7 +114,6 @@
"Bash(docker compose config:*)",
"Bash(docker compose logs:*)",
"Bash(docker compose version:*)",

"Bash(gh pr list:*)",
"Bash(gh pr view:*)",
"Bash(gh pr checks:*)",
Expand All @@ -139,7 +128,6 @@
"Bash(gh workflow list:*)",
"Bash(gh workflow view:*)",
"Bash(gh auth status:*)",

"Bash(composer --version:*)",
"Bash(composer show:*)",
"Bash(composer validate:*)",
Expand All @@ -157,17 +145,14 @@
"Bash(pip list:*)",
"Bash(pip show:*)",
"Bash(pip freeze:*)",

"Bash(php -l:*)",
"Bash(php -m:*)",
"Bash(php -i:*)",
"Bash(php --version:*)",

"Bash(sha256sum:*)",
"Bash(md5sum:*)",
"Bash(nproc:*)",
"Bash(printenv:*)",

"Read(**/.claude/logs/**)"
]
},
Expand All @@ -182,6 +167,15 @@
}
]
},
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/block-polling.sh"
}
]
},
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
Expand Down
85 changes: 85 additions & 0 deletions global-settings/tests/test-block-polling.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
#!/usr/bin/env bash
# test-block-polling.sh — synthetic test harness for block-polling.sh.
#
# Feeds PreToolUse envelopes to the hook and asserts exit 2 (deny) or 0 (allow).
# Target: the hook must block the hand-rolled waiting shapes the 2026-09-12
# velocity diagnosis counted, and must NOT block a short sleep, a one-shot CI
# read, a push, or a grep that merely mentions the words.
#
# Usage:
# ./tests/test-block-polling.sh # run all
# ./tests/test-block-polling.sh -v # verbose
# HOOK=/path/to/hook.sh ./tests/test-block-polling.sh
#
# Exit code: 0 if all tests pass, 1 if any fail. The harness carries its own
# positive control: it first proves the hook denies a known-bad command, so an
# unreadable or empty hook cannot read as green.

set -u
HOOK="${HOOK:-$(cd "$(dirname "$0")/.." && pwd)/block-polling.sh}"
VERBOSE=0; [[ "${1:-}" == "-v" ]] && VERBOSE=1

if [[ ! -r "$HOOK" ]]; then
echo "ERROR: hook not found or unreadable: $HOOK" >&2
exit 1
fi

run_hook() { # $1 = command; returns the hook's exit code
local env
env=$(python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$1")
printf '%s' "$env" | bash "$HOOK" >/dev/null 2>&1
}

pass=0; fail=0; details=()
expect() { # $1 = deny|allow, $2 = command
run_hook "$2"; local rc=$?
local want=0; [[ "$1" == deny ]] && want=2
if [[ $rc -eq $want ]]; then
pass=$((pass+1)); [[ $VERBOSE -eq 1 ]] && echo "ok $1 $2"
else
fail=$((fail+1)); details+=("want $1 (exit $want), got exit $rc: $2")
fi
}

# positive control: a hook that denies nothing must fail this harness
run_hook 'gh run watch 1'; [[ $? -eq 2 ]] || { echo "POSITIVE CONTROL FAILED: hook did not deny 'gh run watch 1'" >&2; exit 1; }

# ── deny: waiting by hand ────────────────────────────────────────────────────
expect deny 'gh run watch 34676564600'
expect deny 'gh run watch 34676564600 --repo ConductionNL/dossiq --exit-status'
expect deny 'gh pr checks 2547 -R ConductionNL/dossiq --watch'
expect deny 'while true; do gh pr checks 5; sleep 30; done'
expect deny 'until gh pr checks 5 | grep -q pass; do sleep 20; done'
expect deny 'for i in 1 2 3; do sleep 1; done; while [ ! -f x ]; do sleep 5; done'
expect deny 'sleep 60'
expect deny 'sleep 120 && gh pr view 5'
expect deny 'cd /tmp && sleep 600'
expect deny 'echo idle'
expect deny 'cd /home/x/memcap-work/eslint-part-2 && echo waiting'
expect deny 'echo "idle"'
expect deny 'timeout 115 tail -f /dev/null; date'
expect deny 'tail -f /dev/null'

# ── allow: legitimate short waits, one-shot reads, everything else ───────────
expect allow 'sleep 5 && curl -s localhost:8080/status.php'
expect allow 'sleep 30'
expect allow 'sleep 59'
expect allow 'gh pr checks 5 -R ConductionNL/dossiq'
expect allow 'gh run view 34676564600 --json jobs'
expect allow 'gh run list --limit 5'
expect allow 'git push origin HEAD'
expect allow 'grep -n "echo idle" transcript.jsonl'
expect allow 'grep -c "gh run watch" file.txt'
expect allow 'echo idle-timeout=30 >> config.ini'
expect allow 'echo waiting-room >> names.txt'
expect allow 'tail -f /var/log/app.log | grep --line-buffered ERROR'
expect allow 'until_date=2026-09-12; echo $until_date'
expect allow 'composer check:strict'
expect allow ''

echo "block-polling: $pass passed, $fail failed"
if [[ $fail -gt 0 ]]; then
printf ' %s\n' "${details[@]}" >&2
exit 1
fi
exit 0
Loading