Skip to content

HOOKS-REFERENCE.md

Latest commit

 

History

History
133 lines (107 loc) · 3.76 KB

HOOKS-REFERENCE.md

File metadata and controls

133 lines (107 loc) · 3.76 KB
Raw

Hooks Reference

Overview

All 7 hooks run locally on your machine as Node.js scripts. They use Claude Code's hook protocol:

  • stdin: Receives a JSON payload with tool_input and/or tool_response
  • stdout: Outputs context to add to Claude's conversation
  • exit 0: Allow the action
  • exit 1: Warn Claude but allow
  • exit 2: Block the action

Hook Details

session-start.js

Property Value
Trigger Session begins
Input None (reads files directly)
Output JSON with additionalContext field
Exit Always 0

What it does:

  1. Reads package.json → detects project name and Angular version
  2. Reads upgrade/state.json → loads upgrade progress
  3. Outputs progress summary into Claude's context

session-stop.js

Property Value
Trigger Session ends
Input None
Output None (writes to files)
Exit Always 0

What it does:

  1. Updates upgrade/state.json with session end timestamp
  2. Records git branch and commit SHA
  3. Appends to upgrade/logs/session-log.jsonl
  4. Optional desktop notification (cross-platform)

pre-bash-guard.js

Property Value
Trigger Before any Bash command
Input { tool_input: { command: "..." } }
Output Error message (stderr) if blocked
Exit 0 (allow), 1 (warn), 2 (block)

Blocked patterns:

  • rm -rf (except upgrade/ and dist/)
  • git reset --hard
  • git push --force
  • Editing node_modules/*.ts

Warned patterns:

  • npm install without --save-dev (during upgrades, prefer dev deps)

pre-edit-guard.js

Property Value
Trigger Before file edits
Input { tool_input: { file_path: "..." } }
Output Error message (stderr) if blocked
Exit 0 (allow), 2 (block)

Protected files:

  • package-lock.json (managed by npm)
  • .git/ (managed by git)
  • node_modules/ (managed by npm)
  • upgrade/state.json (managed by hooks)
  • upgrade/logs/*.jsonl (managed by hooks)

post-bash-gate.js

Property Value
Trigger After Bash command completes
Input { tool_input: { command: "..." }, tool_response: { stdout, stderr, exit_code } }
Output Error context (stderr) if build failed
Exit 0 (pass), 2 (gate failed)

What it does:

  1. Detects ng build, ng test, ng lint commands
  2. If exit code ≠ 0: logs blocker to upgrade/state.json
  3. Appends errors to upgrade/reports/build-errors.md
  4. Optional desktop notification on failure
  5. Detects test regressions (compares to baseline count)

post-edit-typecheck.js

Property Value
Trigger After .ts file edits
Input { tool_input: { file_path: "..." } }
Output TypeScript error output (stderr, informational)
Exit Always 0 (informational only)

What it does:

  1. Runs npx tsc --noEmit --skipLibCheck on the edited file
  2. Reports TypeScript errors for immediate awareness
  3. Does NOT block — full build check is done by post-bash-gate

subagent-log.js

Property Value
Trigger When a subagent is spawned
Input { agent_type, agent_id, session_id }
Output None
Exit Always 0

What it does:

  1. Appends entry to upgrade/logs/agent-audit.jsonl
  2. Records timestamp, agent type, and IDs

Log Files

File Written By Format
upgrade/state.json session-start, session-stop, post-bash-gate JSON
upgrade/logs/session-log.jsonl session-stop JSON Lines
upgrade/logs/agent-audit.jsonl subagent-log JSON Lines
logs/session-audit.jsonl pre-bash-guard JSON Lines
upgrade/reports/build-errors.md post-bash-gate Markdown