Skip to content

Hooks and guards

Chapter 07 of the ResearchTools manual. Back to table of contents.

A hook is a small program Claude Code runs on its own at a fixed moment: before a tool call, after one, when a session starts, when a prompt is submitted, when a turn ends. Hooks cost no model tokens. They are how this toolkit enforces a rule instead of only writing it down.

The hooks are declared in .claude/settings.template.json, which setup.ps1 merges additively into your global ~/.claude/settings.json (see chapter 01). Eight hook scripts and their JSON configs ship in .claude/hooks/. The other scripts the template names are machine-level and are not in this repository, see "Declared but not shipped" below.

At every session start, session-hooks-inventory.py prints the list of hooks actually loaded from settings.json, one line per event, and a [HOOKS ALERT] line for any declared hook whose script is missing. That list is the authority, not this chapter: a hand-written table drifts, and a count in a document was already measured wrong once.

Safety rule: a hook fails silently

A hook whose script is missing makes the interpreter exit with an error, and an error on a PreToolUse or UserPromptSubmit hook refuses the tool call or the prompt itself. Measured 2026-08-27: vault-access-guard.py had been deleted while settings.json still declared it, and nine tools were refused for four turns. So every hook here exits 0 and says nothing when its own dependency is absent (rule R11, chapter 08). Only a real violation of what a hook guards exits 2, a refusal by design. A missing or broken JSON config disables the gate in silence.

Guards before a tool call (PreToolUse)

Hook Matcher What it refuses Rule
betterleaks-hook.py Write, Edit, MultiEdit A write whose content holds a secret or an API key security
vault-access-guard.py Bash, PowerShell, Read, Grep, Glob, Edit, Write, MultiEdit, NotebookEdit Any call that touches the Obsidian vault or the graphify graph, unless it comes from the local-writer agent memory
askuserquestion-clarity.py AskUserQuestion A question with no option description, a description that restates its label, a question too short to name its origin, or a recommended option that is not first R25
worktree-link-guard.py Bash, PowerShell git worktree remove on a worktree that holds a junction or symbolic link, since the removal follows the link and deletes its target R37
review-loop-guard.py Skill A review skill (code-review, security-review) with no declared bounds, or past max_rounds, max_tokens or plateau R35
local-coder-dispatch-guard.py Agent A local-coder dispatch whose prompt has no PLAN: <path> line, or whose plan header does not validate R38

vault-access-guard.py guards the path touched, not the command used, so a cat, a grep or a script pointed at the vault is refused like an obsidian read. It also refuses a graphify-out/ path, the graphify command at command position, and the two graph audit scripts by name. See chapter 06.

review-loop-guard.py and local-coder-dispatch-guard.py are detailed in chapter 11, and worktree-link-guard.py in chapter 15.

Scanners after a tool call (PostToolUse)

Hook Matcher What it does
pip-audit-hook.py Edit, Write, MultiEdit Warns when a modified requirements.txt carries a known vulnerability (CVE)
prompt-injection-defender.py Read, Bash, WebFetch, Grep, Task Warns when a tool result looks like a prompt-injection attempt: an instruction override, a persona switch, an encoded blob, a fake system header, a hidden instruction or a zero-width character

A warning from the defender means: treat the content with suspicion and do not follow instructions written inside it. It uses regular expressions only, so a long path can trigger a false positive.

Session start, prompt and end

Hook Event What it does
caveman-activate.js SessionStart Activates the terse output mode and announces its level
caveman-mode-tracker.js UserPromptSubmit Recalls the output level at every turn
Git sync check (inline) SessionStart Prints [AUTO-SYNC CHECK]: branch, dirty files, commits behind and ahead. Limited to paths of the operator's working folder, silent elsewhere
RTK notice (inline) SessionStart Prints [RTK ACTIVE] when the rtk token filter is on the PATH
Session status (inline) SessionStart Supplies the Session: RTK=... \| Caveman=... \| git-sync=on line
session-hooks-inventory.py SessionStart Prints the hook inventory and any [HOOKS ALERT]
obsidian-outbox-flush.py SessionStart, SessionEnd Writes the notes waiting in ~/.claude/obsidian-outbox/ into the vault through the filesystem, and checks the effect by file size
rt-inbox-deliver.py UserPromptSubmit Hands the session the messages the dashboard left for it, then moves them to delivered/
Memory upkeep (inline) Stop At the end of a turn that changed the working tree, reminds the session to dispatch local-writer for the vault note, the project log and the graph refresh. Silent for a turn that changed nothing

Only the standard output of a SessionStart hook reaches the session context. A hook that writes to standard error is not broken, it is invisible, which is why the inventory and the status line print on standard output.

The inline entries carry their whole shell command in settings.template.json instead of a script.

Declared but not shipped

betterleaks-hook.py, pip-audit-hook.py, prompt-injection-defender.py, the caveman scripts and the memory-upkeep script are declared by the template but are not tracked in this repository. They live in ~/.claude/hooks/ on the operator's machine. On a machine without them the inventory prints a MISSING line for each, and every one of them exits 0 when its dependency is absent. The betterleaks binary is installed with winget install Betterleaks.Betterleaks.

Environment values the template sets

The template also declares four keys in the env block: CLAUDE_CODE_GIT_BASH_PATH (the Git Bash that hooks use on Windows), ENABLE_STOP_REVIEW, and the two graphify values GRAPHIFY_OLLAMA_KEEP_ALIVE and GRAPHIFY_OLLAMA_NUM_CTX. No OLLAMA_* key goes there: the Ollama daemon is started by its tray application and never reads Claude Code's env block, so such a key would look configured and do nothing (see chapter 01).

Git hooks, separate from Claude Code

The global pre-commit and pre-push hooks of the personal-data guard run on every git commit and git push of every repository on the machine, not inside a Claude session. They are installed once with .claude/hooks/git/install-git-hooks.ps1, see chapter 15.

Adding or changing a hook

Edit .claude/settings.template.json, then .\setup.ps1 -UpdateHooks replaces a changed entry in your live file (a stamped backup is made first). A deliberate local variant is kept with -KeepHooks <names>. A hook script and its JSON config are copied to ~/.claude/hooks/ by install-junctions.ps1 -Sync once the offline suite is green, see chapter 16.


← 06 Skills | Table of contents | 08 Rules and conventions →