# rstack hooks Claude Code PreToolUse guards. Each runs inside `_hookfail.run`, so an internal error on a call it guards refuses instead of allowing ([a guard must refuse, not crash](../principles/a-guard-must-refuse-not-crash.md)), and each has its test in `../tests/test_rstack_hooks.py`. Wiring: `settings.example.json`. State goes to `$RSTACK_STATE_DIR` (default `~/.local/state/rstack`). - `_hookfail.py`: the fail-safe wrapper. Five of the guards it was written for ended `except Exception: exit(0)`, and one of them let a machine be created with no shutoff. Two refinements (11-10): `_hookfail.lookup(what, fn, ...)` around a call the guard needs from outside (git, gh, the forge) turns its failure into `ask`, naming what could not be read; and `fail_closed=True` for guards whose matcher is the dangerous act itself (send, merge, push, delete, publish) refuses on any error whatever the triage says. Guards wired to every shell command keep triage instead, or a broken one would refuse the whole session. - `poll-guard.py`: denies the third identical foreground status check in 30 minutes and points at `event-watch wait` in the background. Sessions told in prose to stop polling kept polling; it denies a repeat within 30 minutes of the last one. The one guard that stays fail-open, because it saves turns, not losses. - `trash-guard.py`: checks executed Bash cleanup commands, denies forced recursive `rm` and Finder-scripted deletes, and protects registered paths. Edit/Write contents, echo arguments and heredoc text pass. Uses the model gate's shell reader and unfinished-quote fallback. Finder plays a sound per item; use `/usr/bin/trash`. A copied installation needs `protected_paths.py` and `shell_commands.py` beside the tools in `~/.local/bin`. - `block-main-tree-commit.py`: denies a `git commit` in a protected main checkout (and asks, rather than allows, on its own internal error) (`RSTACK_MAIN_TREES`). A session committed straight onto main while its worktree had the same files; the first version then guarded a moved path for four months, so it now reports a dead path. - `pod-deadline-gate.py`: refuses a pod whose start command does not end the pod itself within a day. "Remember to stop it" dies with the session; a pod that never shut off is the failure. - `pod-create-gate.py`: runs the repo's capacity-receipt gate (`tools/pod-create-gate.py`) fail-safe. An import error used to exit 1, which Claude Code treats as allow. - `conductor-inbox-gate.py`: denies direct SendMessage to the conductor session; workers use `relay`. Every wake replays the conductor's whole context to deliver what was usually an FYI. - `read-the-thread-first.py`: denies a browser click that sends an email unless the session pulled the page text in the last 30 minutes. Wrong replies were wrong about the question, not the voice; a screenshot does not count as a read. - `gate-pipe-guard.py`: denies a lint/test/typecheck gate piped into tail/head/grep without `set -o pipefail`. The pipe's exit code is the last command's, so a failing gate read as green and a broken PR merged. - `agent-stdin-guard.py`: denies `codex exec` or `claude -p` with stdin left open (add `< /dev/null`, or pipe the prompt in). Both read a non-tty stdin and hang forever on a pipe that never closes. - `results-brief-guard.py`: a subagent brief opens "You asked: X. I will: Y." and has a "Done when:" line, the same rule `tools/launch.sh` lints on every job. Drift starts in the brief, when the goal turns into process. - `general-relay-check.py` (Stop, conductor only): blocks the stop once while the reply skips a session whose report was injected; aliases in the inbox's aliases.json; the second stop and any internal error pass. - `general-inbox-relay.py` (UserPromptSubmit, conductor only): injects the session reports the conductor has not relayed to the owner yet and advances a cursor; never blocks a prompt. - `results-report-guard.py` (SubagentStop): the report opens "You asked: X. Shipped: Y" with a count of results, not activity; blocks the stop once, then degrades. - `lane-no-questions.py`: only the conductor (cwd ending `CONDUCTOR_CWD_SUFFIX`, or tmux session `claude-$CONDUCTOR_NAME`) may show a question card. Lanes sat for days on one while the owner was away. - Unattended runs: with `RSTACK_UNATTENDED=1` (the harness sets it for headless `claude -p` jobs), every `ask` becomes a deny with the reason, because an ask prompts even with permissions bypassed and nobody is there to answer. `_hookfail.run(..., timeout=S)` stops a hung body before Claude Code's own timeout turns it into an allow. - Asks only where someone answers: an `ask` is kept in the conductor session or one started with `RSTACK_ATTENDED=1`; anywhere else it becomes a deny that keeps the guard's reason and says to retry or send the decision to the conductor. Interactive lanes ran unwatched in tmux, where an ask prompted (even with permissions bypassed) and the lane sat. Every ask, kept or converted, goes to `$RSTACK_STATE_DIR/hook-asks.jsonl` (guard text only, never the tool input). - `settings.example.json`: the matchers each hook is meant for.