What's New
9 auto-firing hooks that ship as part of the Claude Code plugin. Zero configuration — they activate on npx skills add uditgoenka/autoresearch.
Safety Gates (PreToolUse)
| Hook | What it does |
|---|---|
scout-block
| Blocks vendor dirs, .git/, __pycache__/, dist/, build/, coverage/ — prevents context bloat. Loads .ckignore for per-project customization. Smart Bash argument parsing prevents false positives on string literals.
|
privacy-block
| Blocks .env, SSH keys, .pem, credentials files. Exceptions: .env.example, .env.sample, .env.test. Override with APPROVED: prefix (e.g., APPROVED:.env.local). Bash commands get warnings, not blocks.
|
dangerous-cmd-block
| Blocks git push --force, rm -rf /, git reset --hard, git clean -f, git branch -D, git checkout ., git restore .. Regular git push allowed for /autoresearch:ship.
|
Context Injection (UserPromptSubmit, SubagentStart)
| Hook | What it does |
|---|---|
iteration-context
| Every 5th prompt: injects last 3 TSV rows, iteration count, loop state. Also detects autoresearch commands in prompt text. |
subagent-context
| ~150 tokens per subagent: project root, branch, plans/reports paths, active TSV summary. |
dev-rules-reminder
| Every 5th prompt (deduplicated with iteration-context): re-injects plan path + code standards reference. |
simplify-gate
| Detects shipping verbs (ship, merge, deploy, pr, publish, release). Warns at 400+ LOC diff, blocks at 800+. Ignores negation phrases ("don't ship yet"). |
Session Lifecycle (SessionStart, SessionEnd)
| Hook | What it does |
|---|---|
session-init
| Computes git root, branch, plan/report paths. Creates /tmp/ar-session-{hash}.json state file. Prunes stale sessions >24h.
|
stop-notify
| Terminal notification via OSC 777. Optional webhook via AR_NOTIFY_WEBHOOK env var (fire-and-forget). Formats duration and TSV summary. Cleans up session state.
|
Infrastructure
lib/ar-hook-utils.cjs— Shared utilities: session state management, TSV reading, logging, stdin parsing, output helperslib/ignore.cjs— Vendored gitignore-spec pattern matcher (zero external dependencies)node-hook-runner.sh— Shell wrapper usingexec env -ito silence profile noise for clean JSON outputhooks.json— Auto-registers all 9 hooks on plugin install.ckignore— Baseline blocked patterns (gitignore syntax, customizable per project)
Configuration
Every hook can be individually disabled via environment variable:
AR_DISABLE_SCOUT_BLOCK=1 # disable scout-block
AR_DISABLE_PRIVACY_BLOCK=1 # disable privacy-block
AR_DISABLE_DANGEROUS_CMD=1 # disable dangerous-cmd-block
AR_DISABLE_ITERATION_CTX=1 # disable iteration-context
AR_DISABLE_SUBAGENT_CTX=1 # disable subagent-context
AR_DISABLE_DEV_RULES=1 # disable dev-rules-reminder
AR_DISABLE_SIMPLIFY_GATE=1 # disable simplify-gate
AR_DISABLE_SESSION_INIT=1 # disable session-init
AR_DISABLE_STOP_NOTIFY=1 # disable stop-notifyDesign Decisions
- SessionEnd (not Stop) for notifications — Stop fires per-turn, SessionEnd fires exactly once
- Fail-open on all errors — hooks never break the session, wrapped in try/catch → exit 0
- Iteration-based throttling (every 5th prompt) — matches loop cadence, not wall-clock time
- Session state via temp files — hooks are subprocesses, can't share env vars
- Smart Bash parsing —
extractPathTokens()splits on pipes/semicolons, avoids false positives on string literals - Build tool allowlist — npm, yarn, pnpm, bun, pip, cargo, go, rustc, make, cmake, mvn, gradle, docker, kubectl, terraform, helm
Testing
105 tests covering all 9 hooks:
bash tests/test-hooks.sh
# === Results: 105/105 passed === (all passed)Docs Updated
README.md— hooks section + version badgeguide/hooks.md— complete hook reference guidedocs/system-architecture.md— hook system architecture sectiondocs/project-changelog.md— v2.1.1 changelog entryCONTRIBUTING.md— hook development guide