Feature Request: Add hook exit code for "user-visible message without context injection"

Resolved 💬 4 comments Opened Dec 31, 2025 by james5294 Closed Feb 17, 2026

Summary

Hooks currently lack a clean way to display informational messages to users without adding them to Claude's context. This forces plugin authors to use workarounds that get mislabeled as errors.

Use Case

Plugins like claude-mem want to:

  • ✅ Show startup messages to users (localhost UI links, update notices, tips)
  • ✅ Keep these messages out of Claude's context (saves tokens, keeps conversation clean)
  • ❌ But currently get labeled as "Plugin hook error:" which confuses users

Current Behavior

According to the hooks documentation:

| Approach | Result |
|----------|--------|
| Exit 0 + stdout (SessionStart) | Added to Claude's context ❌ |
| Exit 0 + stdout (other hooks) | Verbose mode only ❌ |
| Exit 2 + stderr | Blocking error ❌ |
| Non-zero + stderr | Labeled as "Plugin hook error" or "Failed with non-blocking status code" ❌ |

There's no option for "show to user, don't add to context, don't label as error."

Current Workaround

Plugins use exit code 3 + stderr, accepting the "error" mislabeling:

SessionStart:startup says: Plugin hook error: 📝 Claude-Mem Context Loaded
       ℹ️  Note: This appears as stderr but is informational only

This works functionally but:

  • Confuses users who think there's an actual error
  • Forces plugins to add disclaimers like "This appears as stderr but is informational only"
  • Looks unprofessional

Proposed Solution

Add a documented exit code (e.g., exit code 3) or JSON output option for "informational user message":

Option A: New Exit Code

Exit code 3 + stdout → Display to user, don't add to context, label as "info" not "error"

Option B: JSON Output

{
  "userMessage": "📝 Plugin loaded successfully",
  "addToContext": false
}

Expected Behavior After Fix

SessionStart:startup says: 📝 Claude-Mem Context Loaded

Or with an "info" label:

SessionStart:Callback hook info: 📝 Claude-Mem Context Loaded

Context

Environment

  • Claude Code: Latest
  • Platform: macOS, but applies to all platforms

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗