Hooks Event Reference

Claude Code’s hook system supports 29 event types, 5 hook types, per-event matchers, and smart behaviors. Hooks are the only deterministic control points in the agentic harness where execution is guaranteed — a prompt can be ignored, but a hook cannot.

For hook fundamentals and configuration, see the Hooks Guide. This page is the full event reference.

Five hook types are available.

MoAI-ADK hooks go beyond simple event handling to perform intelligent behaviors.

When permission for a read-only tool (Read, Grep, Glob) is denied, the hook automatically triggers a retry. This mitigates the problem of permission prompts not being displayed for background agents.

On agent stop failure, differentiated responses are provided by error type. This ensures stability in long-running sessions.

After context compaction, important session notes (progress state, SPEC references) are automatically restored. Context compaction is a trade that saves tokens at the cost of information — this hook protects the essential information from that loss.

When a sub-agent starts, the necessary context (project rules, MX tags, progress state) is automatically injected.

Matchers let you filter so a hook runs only under specific conditions. Attaching hooks to every event increases execution cost accordingly, so narrowing scope with matchers is the default.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": { "toolName": "Bash" },
      "hooks": [{
        "type": "command",
        "command": "echo 'Bash tool detected'",
        "timeout": 5
      }]
    }]
  }
}

Environment variables can be managed persistently via the CwdChanged and FileChanged hooks.

# .claude/hooks/moai/handle-cwd-changed.sh
# Persist environment variables via CLAUDE_ENV_FILE
echo "MOAI_PROJECT_DIR=$(pwd)" >> "$CLAUDE_ENV_FILE"

This lets you keep environment variables across sessions and automatically reconfigure the environment on directory changes.

• Hooks Guide — hook fundamentals and configuration
• settings.json Guide — the full settings.json reference
• CLI Reference — details on the moai hook command