Hooks Reference
Hooks run automatically at defined points in a Claude Code session. You do not invoke them.
21 hooks are registered and live. This page documents 23 files in total — the difference is a git hook and its installer, which ship through the same manifest but receive no Claude Code event.
Where registrations live
A hook is registered if any surface names it, and reading only one is a
documented defect here: BUG-093 was filed as "registered in no hooks.json" when
the guard was in fact registered in three agents' frontmatter. This page takes
its inventory from
scripts/tests/setup/lib/hook-registry.sh,
the canonical reader for all seven surfaces — plugin hooks.json, the three
shipped settings*.json, agent/skill/command frontmatter, the user-global
skills and agents, and profile patches.
The counts below are what was measured, not a claim about completeness: a verdict
that names no number reads identically for 26 checks and for zero
(docs/solutions/patterns/verdict-needs-a-denominator.md).
| Measurement |
Count |
| registry rows |
21 |
| registered hooks (distinct) |
21 |
| deploy-manifest entries |
8 |
| shipped but not registered |
2 |
| checksum-pinned |
23 |
| total files documented |
23 |
The exit-code contract
Hook exit codes are not a plain success/failure pair, and getting this wrong
is what made the previous version of this page misleading:
| Exit |
Meaning |
0 |
Allow the call. stdout goes to the transcript. |
2 |
DENY the call. stderr is fed back to the model as the reason. |
| any other non-zero |
A non-blocking error: surfaced to the user, and the call proceeds. |
So a guard that means to block and returns 1 does not block. Both the exit code
and the stream are load-bearing (BUG-054, BUG-096), and the contract is asserted
by plugins/vt-base/tests/test-pretooluse-hook-contract.sh.
continueOnError in the tables below is reproduced verbatim from the
registration rather than translated into a "blocking" verdict: it governs what
happens when the hook itself errors, which is a different question from whether
the hook denies.
By event
SessionStart
UserPromptSubmit
| Hook |
Tools (matcher) |
Timeout |
continueOnError |
Pinned |
What it does |
Plugin |
| intent-skill-matcher.sh |
— |
3 |
true |
yes |
UserPromptSubmit hook for intent-based skill suggestion |
vt-base |
| Hook |
Tools (matcher) |
Timeout |
continueOnError |
Pinned |
What it does |
Plugin |
| backup-before-write.sh |
— |
— |
— |
yes |
PreToolUse hook for research-implement skill |
vt-base |
| block-writes.sh |
— |
— |
— |
yes |
Policy enforcement hook for read-only review agents |
vt-base |
| check-doc-prerequisites.sh |
— |
— |
— |
yes |
PreToolUse hook for docs-pipeline-orchestrator |
vt-base |
| claudeignore-guard.sh |
Read|Grep|Glob |
3 |
false |
yes |
PreToolUse hook enforcing .claudeignore patterns |
vt-base |
| partition-guard.sh |
Write|Edit |
3 |
true |
yes |
Pre-Write Partition Enforcement |
vt-base |
| secret-scanner.sh |
Write|Edit|MultiEdit|NotebookEdit |
5 |
false |
yes |
Secret Scanner — 3-Layer Detection System (SPEC-088) |
vt-base |
| supply-chain-guard.sh |
Bash |
30 |
true |
yes |
PreToolUse: CVE + OSSF malicious package check |
vt-base |
| vault-write-guard.sh |
— |
— |
— |
yes |
Restricts Write/Edit to the IMS vault path only |
vms |
| venv-guard.sh |
Bash |
3 |
true |
yes |
PreToolUse hook blocking bare pip / python -m pip / poetry |
vt-base |
PostToolUse
| Hook |
Tools (matcher) |
Timeout |
continueOnError |
Pinned |
What it does |
Plugin |
| auto-format.sh |
Write|Edit |
10 |
true |
yes |
Run project-appropriate formatter after Write/Edit |
vt-base |
| check-xlsx-formulas.sh |
— |
— |
— |
yes |
PostToolUse hook for xlsx skill |
vt-base |
| commit-size-monitor.sh |
Bash |
5 |
true |
yes |
Post-Commit Size & Partition Check |
vt-base |
| security-lint.sh |
Write |
10 |
true |
yes |
Security Lint - Quick security checks on written files |
vt-base |
Stop
| Hook |
Tools (matcher) |
Timeout |
continueOnError |
Pinned |
What it does |
Plugin |
| autonomy-continue.sh |
— |
2 |
true |
yes |
Stop hook for auto-continuing reassurance-seeking pauses |
vt-base |
| quality-gate.sh |
— |
60 |
true |
yes |
Stop hook for automated quality checks |
vt-base |
PreCompact
| Hook |
Tools (matcher) |
Timeout |
continueOnError |
Pinned |
What it does |
Plugin |
| precompact-skill-inventory.sh |
— |
5 |
true |
yes |
PreCompact hook for skill awareness preservation |
vt-base |
Shipped through the hook manifest, but not Claude Code hooks
| File |
Type |
What it is |
Plugin |
| install-hooks.sh |
installer |
Install Git hooks to the current repository |
vt-base |
| pre-commit |
git-hook |
⚠ bash, NOT sh (BUG-122). This script uses read -r -d '' in three loops — the .env |
vt-base |