Skip to content
Open
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: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

<p>Stop babysitting coding agents: cards you drop in Ready come back as tested, reviewed PRs.</p>

<p>9 skills (5 you type, 4 the board runs) Β· 9 commands Β· 6 guard hooks</p>
<p>9 skills (5 you type, 4 the board runs) Β· 9 commands Β· 7 guard hooks</p>

<p>
<img alt="Version" src="https://img.shields.io/badge/version-3.3.0-1f883d?style=flat-square">
Expand Down Expand Up @@ -154,6 +154,7 @@ Run automatically once installed. Python stdlib, JSON in, JSON out.
| [guard-secrets](hooks/guard-secrets.py) | Blocks reading or piping dotenv files, SSH keys and credential files; key names via `super-board-env-check.sh` |
| [guard-key-literals](hooks/guard-key-literals.py) | Blocks a live-looking API key written into a file; flags one already there |
| [guard-delete-outside](hooks/guard-delete-outside.py) | Blocks `rm`, `find -delete` and `git clean` aimed outside the project, `~` or `/` |
| [guard-approval-edit](hooks/guard-approval-edit.py) | Blocks editing a posted πŸ™‹ approval request; a correction is a new comment |
| [guard-protected-push](hooks/guard-protected-push.py) | Opt-in (`onboard` asks, or `install.sh --protect-main`): blocks direct and force pushes to main/master/base |
| [README sync](scripts/super-board-readme-sync.py) | Regenerates the skill table; pre-commit and PostToolUse hooks keep it fresh |
| [cleanup-wt](hooks/cleanup-wt.py) | Removes merged worktrees and branches after each merge and at session start, with a recovery file |
Expand Down
5 changes: 5 additions & 0 deletions hooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ protected-push guard (opt-in) and the dev-only skill-eval gate.
- `guard-secrets.py` β€” PreToolUse `Bash|Read|Grep`: denies reading or piping dotenv files, SSH keys, `.npmrc`, `credentials(.json)`, service-account JSON and `.pem`; `.env.example` stays readable. One plain call to `super-board-env-check.sh KEY…` is allowed: it prints present / empty / missing per key and never a value (no pipe, chain or redirect may ride along).
- `guard-key-literals.py` β€” PreToolUse `Edit|MultiEdit|Write|NotebookEdit|Bash`: denies writing a live-looking API key into a file; PostToolUse `Edit|MultiEdit|Write|NotebookEdit`: flags one already on disk. Reports line numbers, never the value.
- `guard-delete-outside.py` β€” PreToolUse `Bash`: denies `rm`, `rmdir`, `unlink`, `find … -delete` / `-exec rm` and `git clean` whose target resolves outside `$CLAUDE_PROJECT_DIR`, and always `/` or `~` itself (honours `cd X &&`, `git -C X`, `~`, `$HOME`). Inside `/tmp`, `/private/tmp`, `/var/folders` and `$TMPDIR` stays allowed. A path whose value is only known at run time (`$(…)`, a variable set earlier in the same command) is allowed.
- `guard-approval-edit.py` β€” PreToolUse `Bash`: denies editing an existing comment (`gh issue|pr comment --edit-last`, a PATCH to `issues/comments/<id>`, GraphQL `updateIssueComment`) whose new body carries an `approval-request:` line or a `Reason tag: … πŸ™‹` line. The merge gate refuses an edited request, so the human's `done` would be lost; post a new comment instead. Reads the body from the command (inline, heredoc) and from the files it names (`--body-file`, `-F body=@file`, `--input`, `$(cat file)`, `< file`). Posting a new comment is never blocked. `SB_ALLOW_APPROVAL_EDIT=1` turns it off for a session.
- `cleanup-wt.py` β€” SessionStart (`--auto`): when a base branch tip moved since the last session, removes worktrees and local branches already merged into it. The merge gate also runs it with `--post-merge` after every merge. Never deletes unmerged work (a dirty worktree on a merged branch is wip-committed and its branch kept), never touches bases or the worktree it runs in, and writes a recovery TSV to `<git-common-dir>/cleanup-wt/<timestamp>.tsv` before acting. Restore with `git branch <name> <sha>`. A manual dry run (`python3 .claude/hooks/cleanup-wt.py`, then `--apply`) still works.

## Enable
Expand All @@ -32,6 +33,10 @@ project and merges the block below (kept in `settings-snippet.json`) into
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-delete-outside.py"
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-approval-edit.py"
}
]
},
Expand Down
106 changes: 106 additions & 0 deletions hooks/guard-approval-edit.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
#!/usr/bin/env python3
"""PreToolUse(Bash) guard: never edit a πŸ™‹ approval request; post a new comment.

super-board-approval.py refuses a request comment whose updated_at differs from its
created_at ("approval request was edited; post a fresh request"): an edit could change
what the human's `done` approved. A lane that edits its own request to add a link or
fix a line loses the human's `done` and costs a review round.

Denied: an edit of an existing comment (`gh issue|pr comment --edit-last`, a PATCH to
`issues/comments/<id>`, a GraphQL `updateIssueComment`) whose new body carries an
`approval-request:` line or a `Reason tag: … πŸ™‹` line. The body is read from the command
itself (inline `--body`, a heredoc) and from any file it names (`--body-file`, `-F`,
`--input`, `body=@file`, `$(cat file)`, `< file`). Posting a new comment is never blocked.

SB_ALLOW_APPROVAL_EDIT=1 in Claude Code's environment turns it off for a session.
Its own errors never block a tool call: anything unexpected exits 0 with no output.
"""
import json
import os
import re
import shlex
import sys

STOP = r"[^;&|\n]*" # stay inside one simple command
PATCH = r"(?:-X\s*PATCH|--method[ =]PATCH)"
EDIT = re.compile(
rf"\bgh\s+(?:issue|pr)\s+comment\b{STOP}--edit-last"
rf"|\bgh\s+api\b{STOP}{PATCH}{STOP}issues/comments/"
rf"|\bgh\s+api\b{STOP}issues/comments/\d+{STOP}{PATCH}"
r"|\bupdateIssueComment\b", re.I)
REQUEST = re.compile(r"approval-request:|Reason tag:[^\n]*πŸ™‹")
FILE_FLAGS = {"--body-file", "-F", "--field", "-f", "--raw-field", "--input"}

REASON = (
"Blocked: this edits a πŸ™‹ approval request.\n"
"The merge gate refuses an edited request (\"approval request was edited\"), so the "
"human's `done` is lost. Never edit a request after posting: post a NEW comment instead. "
"A follow-up note carries no `Reason tag: πŸ™‹` and no `approval-request:` line; a changed "
"request is a fresh full block with the gate's `approval-request:` line copied verbatim "
"(block-template.md β†’ \"Approval request\"). If this edit really is intended, ask the user "
"to run it, or start Claude Code with SB_ALLOW_APPROVAL_EDIT=1.")


def named_files(command):
"""Files whose text becomes the new body without appearing in the command."""
files = re.findall(r"\$\(\s*cat\s+['\"]?([^)'\"\s]+)['\"]?\s*\)", command)
files += re.findall(r"(?<![<\d])<\s*['\"]?([^\s<'\";&|]+)", command)
try:
tokens = shlex.split(command, posix=True)
except ValueError:
return files
for i, tok in enumerate(tokens):
value = None
if tok in FILE_FLAGS and i + 1 < len(tokens):
value = tokens[i + 1]
elif "=" in tok and tok.split("=", 1)[0] in FILE_FLAGS:
value = tok.split("=", 1)[1]
if value is None:
continue
if "=@" in value:
value = value.split("=@", 1)[1]
elif value.startswith("@"):
value = value[1:]
elif "=" in value:
continue # an inline key=value: the command text already holds it
if value and value != "-":
files.append(value)
return files


def check(command, cwd):
"""None when allowed, else the deny reason."""
if not EDIT.search(command):
return None
if REQUEST.search(command):
return REASON
for name in named_files(command):
path = os.path.join(cwd, os.path.expanduser(name))
try:
with open(path, encoding="utf-8") as stream:
if REQUEST.search(stream.read()):
return REASON
except (OSError, ValueError):
continue
return None


def main():
try:
if os.environ.get("SB_ALLOW_APPROVAL_EDIT") == "1":
return
payload = json.loads(sys.stdin.read() or "{}")
command = (payload.get("tool_input") or {}).get("command")
if not isinstance(command, str):
return
reason = check(command, payload.get("cwd") or os.getcwd())
if reason:
print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": reason}}))
except Exception:
pass # a broken guard must never block unrelated work


if __name__ == "__main__":
main()
4 changes: 4 additions & 0 deletions hooks/settings-snippet.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-delete-outside.py"
},
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-approval-edit.py"
}
]
},
Expand Down
3 changes: 2 additions & 1 deletion skills/super-board/references/block-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,8 @@ issue comment. It records the full PR head and the exact policy/human steps bein
confirmed. The issue must be linked by the PR's closing reference (`Closes #N`).
For a standalone PR, post the canonical request on the PR instead. Keep a single
request location: the PR's status comment links to the issue request and does not
repeat `Reason tag: πŸ™‹` or `approval-request:`. Never edit a request after posting;
repeat `Reason tag: πŸ™‹` or `approval-request:`. Never edit a request after posting
(the gate refuses an edited request; `guard-approval-edit.py` denies the edit);
post a new one when the code, steps or actual human question changes. Do not
repost the same pending request on every poll or retry. Generic credential or
product blocks without a PR remain manual; a bare `done` does not automate them.
Expand Down
6 changes: 5 additions & 1 deletion skills/super-board/references/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -502,7 +502,11 @@ on the base branch**.
human comments `done` after the current pinned request, the wave planner
verifies their permission and the head before resuming Review. For exits
7 and 8, copy the gate's `approval-request:` line into the canonical issue
block; link it from the PR without duplicating the request.
block; link it from the PR without duplicating the request. Post that block
ONCE, as the exit's LAST GitHub write (after the PR comment, labels and card
move), and never edit it: the gate refuses an edited request and the human's
`done` is lost. A correction is a new comment; a changed request is a fresh
full block. `hooks/guard-approval-edit.py` denies the edit.
β†’ do NOT leave a card in Review on exit 2, 3, 5, 7 or 8. A card left in Review is
re-picked next tick and re-reviewed forever, which is the re-dispatch waste
tracked in issue #10. Exits 4 and 6 are the exceptions: 4 simply queued, and
Expand Down
3 changes: 3 additions & 0 deletions skills/super-board/references/writing-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -412,3 +412,6 @@ that comment; it pins the repository, PR, full head and policy/human-step scope.
Other threads link to that request without repeating its machine lines. A trusted
human replies `done` in that same thread. Labels are status display, never approval.
Do not edit the request or approval comment; changed code or steps need a fresh request.
Post the request once, as the last write of the exit. A follow-up is a new comment with no
πŸ™‹ `Reason tag:` line: a newer πŸ™‹ block supersedes the request even without its machine line.
`guard-approval-edit.py` denies an edit whose body keeps a request line.
2 changes: 1 addition & 1 deletion tests/test-get.sh
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ out=$(bash "$GET" --target "$T" 2>&1) || fail "grouped-output install failed: $o
order=$(printf '%s\n' "$out" | grep -oE '^(🧩|πŸ”|πŸ“¦|πŸ”§|🧠|πŸ”’|πŸŽ‰|πŸ‘‰)' | tr -d '\n')
[ "$order" = "πŸ§©πŸ”πŸ“¦πŸ”§πŸ§ πŸ”’πŸŽ‰πŸ‘‰" ] || fail "groups out of order ($order): $out"
printf '%s\n' "$out" | grep -q '^ βœ“ curl Β· tar Β· python3 Β· gh Β· jq Β· node$' || fail "checks line wrong: $out"
printf '%s\n' "$out" | grep -q '^ πŸ›‘οΈ 6 guard hooks β†’ .claude/settings.json (new file)$' || fail "guard line wrong: $out"
printf '%s\n' "$out" | grep -q '^ πŸ›‘οΈ 7 guard hooks β†’ .claude/settings.json (new file)$' || fail "guard line wrong: $out"
printf '%s\n' "$out" | grep -q '^ ! CLAUDE.md holds its own rules β€” onboard offers a merge$' || fail "CLAUDE.md hint missing: $out"
printf '%s\n' "$out" | grep -q '^🧠 helper skills: installed$' || fail "helper line wrong: $out"
[ "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" -le 13 ] || fail "output should stay ≀ 13 lines: $out"
Expand Down
27 changes: 27 additions & 0 deletions tests/test-guard-hooks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,33 @@ dd allow 'T=$(mktemp -d); rm -rf "$T/x"' "unknowable value is allowed"
dd allow 'echo "rm -rf /"' "quoted text is not a command"
dd allow 'ls -la ~ && git status' "no deletion"

# ---- guard-approval-edit -----------------------------------------------------
# The merge gate refuses an edited πŸ™‹ request ("approval request was edited"), so the
# human's `done` is lost. An edit whose new body keeps a request line is denied; posting
# a new comment never is.
AP=$(mktemp -d)
printf '[reviewer] [blocker] πŸ™‹ Your turn\nReason tag: πŸ™‹ needs you\napproval-request: {"head":"%s","pr":7}\n' \
"$(printf 'a%.0s' $(seq 1 40))" > "$AP/request.md"
printf '[reviewer] [report] βœ… link: PR #7\n' > "$AP/note.md"
ae() { expect "$1" guard-approval-edit.py "$(bash_cmd "$2" "$AP")" "$3"; }
ae deny 'gh issue comment 7 --edit-last --body-file request.md' "edit-last with a request file"
ae deny 'gh pr comment 7 --edit-last --body "approval-request: {}"' "edit-last with an inline request"
ae deny 'gh api -X PATCH repos/o/r/issues/comments/991 -F body=@request.md' "PATCH with body=@file"
ae deny 'gh api repos/o/r/issues/comments/991 --method PATCH -f body="$(cat request.md)" && echo ok' "PATCH with \$(cat file)"
ae deny "gh api repos/o/r/issues/comments/991 -X PATCH --input - <<'EOF'
{\"body\": \"approval-request: {}\"}
EOF" "PATCH with a heredoc"
ae deny 'gh api repos/o/r/issues/comments/991 -X PATCH --input - < request.md' "PATCH with < file"
ae deny "gh api graphql -f query='mutation{updateIssueComment(input:{id:\"X\",body:\"Reason tag: πŸ™‹ needs you\"}){issueComment{id}}}'" "GraphQL updateIssueComment"
ae allow 'gh issue comment 7 --body-file request.md' "posting a new request"
ae allow 'gh api repos/o/r/issues/7/comments -F body=@request.md' "POSTing a new request via api"
ae allow 'gh issue comment 7 --edit-last --body-file note.md' "editing a plain note"
ae allow 'cat request.md && git status' "unrelated command"
expect allow guard-approval-edit.py "not json" "garbage input fails open"
OUT=$(printf '%s' "$(bash_cmd 'gh issue comment 7 --edit-last --body-file request.md' "$AP")" | SB_ALLOW_APPROVAL_EDIT=1 python3 "$H/guard-approval-edit.py")
[ -z "$OUT" ] || fail "SB_ALLOW_APPROVAL_EDIT=1 should turn the guard off"; PASS=$((PASS + 1))
rm -rf "$AP"

# ---- dev/gate-skill-evals (Stop; pack + EricOS only) -------------------------
G=$(mktemp -d); G=$(cd "$G" && pwd -P)
git -C "$G" init -q -b main; git -C "$G" config user.email t@t; git -C "$G" config user.name t
Expand Down
6 changes: 3 additions & 3 deletions tests/test-install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ cat > "$T/.claude/settings.json" <<'JSON'
{"permissions":{"allow":["Bash(ls:*)"]},"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"echo mine"}]}],"Stop":[{"hooks":[{"type":"command","command":"echo stop"}]}]}}
JSON
"$INSTALL" "$T" >/dev/null 2>&1
for h in guard-worktree-path.py guard-secrets.py guard-key-literals.py guard-delete-outside.py guard-protected-push.py cleanup-wt.py; do
for h in guard-worktree-path.py guard-secrets.py guard-key-literals.py guard-delete-outside.py guard-approval-edit.py guard-protected-push.py cleanup-wt.py; do
[ -f "$T/.claude/hooks/$h" ] || fail "hook $h was not installed"
done
[ ! -e "$T/.claude/skills/cleanup-wt" ] || fail "cleanup-wt is a hook now, not a skill"
Expand All @@ -200,7 +200,7 @@ jq -e '[.hooks.SessionStart[].hooks[].command | select(contains("cleanup-wt.py -
|| fail "the cleanup-wt SessionStart hook is not wired by default"
jq -e '[.hooks[][].hooks[].command | select(contains("guard-protected-push"))] | length == 0' "$S" >/dev/null \
|| fail "the protected-push guard is opt-in: it must not be wired without --protect-main"
for h in guard-worktree-path guard-secrets guard-key-literals guard-delete-outside; do
for h in guard-worktree-path guard-secrets guard-key-literals guard-delete-outside guard-approval-edit; do
jq -e --arg h "$h" '[.hooks[][].hooks[].command | select(contains($h))] | length > 0' "$S" >/dev/null || fail "$h not wired in settings"
done
ls "$T/.claude/" | grep -q '^settings.json.bak-' || fail "no backup written before changing settings.json"
Expand Down Expand Up @@ -269,7 +269,7 @@ OUT=$(SUPER_BOARD_QUIET_NEXT=1 "$INSTALL" "$T" 2>&1)
[ "$(echo "$OUT" | head -1)" = "πŸ”§ installing" ] || fail "quiet mode should start at the installing group, got: $OUT"
echo "$OUT" | grep -q "next:" && fail "quiet mode must not print the next step"
echo "$OUT" | grep -q "βœ“ skills, scripts and workflows β†’ .agents/" || fail "quiet mode should print the grouped files line"
echo "$OUT" | grep -q "πŸ›‘οΈ 6 guard hooks β†’ .claude/settings.json (new file)" || fail "guard line should count hooks, got: $OUT"
echo "$OUT" | grep -q "πŸ›‘οΈ 7 guard hooks β†’ .claude/settings.json (new file)" || fail "guard line should count hooks, got: $OUT"
[ "$(echo "$OUT" | wc -l | tr -d ' ')" -le 3 ] || fail "grouped output should be ≀ 3 lines here, got: $OUT"
rm -rf "$T"

Expand Down