claude-mem/docs/reference/claude-code/hook-responses.md

Claude Code Hook Response Format Documentation

Source: Official Claude Code Docs v2025

Last Verified: 2025-08-31

Common Hook Response Fields

All hooks can return these common fields:

{
  "continue": true,              // Whether Claude should continue (default: true)
  "stopReason": "string",        // Message shown when continue is false
  "suppressOutput": true,        // Hide stdout from transcript (default: false)
  "systemMessage": "string"      // Optional warning message shown to user
}

Hook-Specific Response Formats

PreCompact Hook

IMPORTANT: PreCompact does NOT support hookSpecificOutput

{
  "continue": true,
  "suppressOutput": true
}

SessionStart Hook

SessionStart DOES support hookSpecificOutput:

{
  "continue": true,
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Context string to add to session"
  }
}

PreToolUse Hook

{
  "continue": true,
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "Reason for decision"
  }
}

PostToolUse Hook

{
  "decision": "block",  // Optional - blocks further processing
  "reason": "Explanation",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

UserPromptSubmit Hook

{
  "decision": "block",  // Optional - blocks the prompt
  "reason": "Security policy violation",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Additional context for the prompt"
  }
}

Exit Codes

• 0: Success - hook executed successfully
• 1: Error - shown to user with stdout
• 2: Error - shown to Claude with stderr

Common Mistakes to Avoid

\u274c INCORRECT: Using wrong field names

// WRONG
{
  "decision": "block",      // \u274c Wrong field
  "reason": "Error message"  // \u274c Wrong field
}

\u2705 CORRECT: Using official field names

// RIGHT
{
  "continue": false,
  "stopReason": "Error message"
}

\u274c INCORRECT: Adding hookSpecificOutput to PreCompact

// WRONG - PreCompact doesn't support this
{
  "hookSpecificOutput": {
    "hookEventName": "PreCompact",
    "status": "success"
  }
}

\u2705 CORRECT: Simple response for PreCompact

// RIGHT
{
  "continue": true,
  "suppressOutput": true
}

References

• Official Docs: https://docs.anthropic.com/en/docs/claude-code/hooks
• Hook Examples: https://docs.anthropic.com/en/docs/claude-code/hooks-guide