Lifecycle Hooks

Massu AI includes 17 MCP lifecycle hooks and 11 shell utility hooks that run automatically during Claude Code sessions. Together they capture observations, inject context, enforce rules, filter output, preserve state, and drive the auto-learning pipeline -- all without any manual effort from the developer.

How Hooks Work

Hooks are compiled TypeScript files that Claude Code executes at specific lifecycle events. Each hook:

1. Receives JSON on stdin with session context (session ID, transcript path, tool details)
2. Processes the input (reads databases, analyzes tool calls, generates context)
3. Outputs result on stdout (plain text for context injection, JSON for structured responses)
4. Exits within 5 seconds to avoid blocking Claude Code

Hooks are compiled with esbuild into standalone JavaScript files bundled inside the @massu/core npm package (dist/hooks/). They are automatically configured in .claude/settings.local.json when you run npx massu init. They have no runtime dependencies beyond Node.js built-ins and the bundled Massu AI modules.

The 17-Hook Lifecycle

Session Lifecycle Flow

Session Start
  |
  v
[session-start hook] --> Injects memory context
  |
  v
User writes prompt
  |
  v
[user-prompt hook] --> Captures prompt, links to task
[intent-suggester hook] --> Suggests relevant commands
  |
  v
Claude Code prepares a tool call
  |
  v
[pre-tool-use-gate hook] --> Single-spawn check: security policies +
                             feature-impact protection on deletions
  |
  v
Claude Code processes (reads, edits, runs commands)
  |
  v
[post-tool-use hook] --> Captures observation per tool call
[post-edit-context hook] --> Surfaces rules on file edits
[cost-tracker hook] --> Records token usage
[quality-event hook] --> Detects quality signals
[fix-detector hook] --> Detects fix-shape diffs (arms auto-learning)
[classify-failure hook] --> Scores fix as KNOWN/SIMILAR/NEW
[incident-pipeline hook] --> Triggers when incidents/*.md written
[rule-enforcement-pipeline hook] --> Triggers when feedback_*.md written
  |
  v
(if context window fills up)
[pre-compact hook] --> Snapshots state before compaction
[session-start hook] --> Re-injects context after compact
  |
  v
Session ends
  |
  v
[auto-learning-pipeline hook] --> Forcing function: blocks Stop until
                                  fix-detector arm has produced an
                                  incident report + rule + enforcement
[session-end hook] --> Generates summary, archives CURRENT.md

Zero Effort for Users

You do not need to interact with hooks directly. They run silently in the background:

• No commands to remember: Hooks trigger automatically at the right lifecycle events
• No performance impact: Each hook completes in under 500ms
• No configuration needed: Hooks use your massu.config.yaml automatically
• Best-effort execution: If a hook fails, it exits silently without blocking Claude Code

Hook Compilation

Hooks are written in TypeScript and compiled with esbuild:

cd packages/core && npm run build:hooks

This produces standalone JavaScript files in packages/core/dist/hooks/ that are referenced by .claude/settings.local.json during installation. Run npx massu install-hooks to update the hooks configuration.

Detailed Hook Documentation

Click any hook below for complete documentation including input/output formats, configuration, and examples:

• session-start -- Context injection at session start
• session-end -- Summary generation and archival
• pre-tool-use-gate -- Consolidated PreToolUse single-spawn check (security + delete-protection)
• post-tool-use -- Observation capture after tool calls
• user-prompt -- Prompt capture and task linking
• pre-compact -- State preservation before compaction
• pre-delete-check -- Deletion protection via feature impact (back-compat; folded into pre-tool-use-gate)
• post-edit-context -- Rule surfacing after file edits
• security-gate -- Security policy validation before tool execution (back-compat; folded into pre-tool-use-gate)
• cost-tracker -- Token usage tracking per tool call
• quality-event -- Quality signal detection after tool calls
• intent-suggester -- Command suggestion based on prompt intent
• fix-detector -- Fix-shape detection via git diff (arms auto-learning pipeline)
• classify-failure -- Scores detected fix against known failure classes
• incident-pipeline -- Triggers rule derivation when incident reports are written
• rule-enforcement-pipeline -- Triggers enforcement placement when feedback rules are written
• auto-learning-pipeline -- Stop-hook forcing function for the incident → rule → enforcement chain

Shell Hooks (11)

In addition to the 11 MCP lifecycle hooks, Massu AI includes 11 shell utility hooks located in scripts/hooks/. These hooks are invoked at specific points to enforce policies, filter output, and automate routine tasks.

Shell Hook Configuration

Shell hooks are configured in .claude/settings.local.json alongside the MCP lifecycle hooks. They are installed by npx massu init and updated by npx massu install-hooks.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "node dist/hooks/post-tool-use.js" }] },
      { "matcher": "*", "hooks": [{ "type": "command", "command": "bash dist/hooks/mcp-usage-tracker.sh" }] }
    ]
  }
}

Shell hooks follow the same stdin/stdout contract as MCP hooks: they receive JSON on stdin, write output on stdout, and must exit within 5 seconds.