Feature Request: External Event Push API for Background Process Notifications

Feature Request: External Event Push to Claude Sessions

Problem Statement

Currently, Claude Code operates on a request-response model where Claude only acts when:

1. The user sends a message
2. A hook fires after Claude performs an action (PostToolUse, Stop, etc.)

This creates a limitation for long-running background processes:

• Background server completes a task
• No way to notify the active Claude session
• User must manually prompt Claude to check status
• Breaks the conversational flow

Current Limitations

User prompts Claude → Claude starts background process
                             ↓
                      Process runs (5 min)
                             ↓
                      Process completes ✓
                             ↓
                      [NO WAY TO NOTIFY CLAUDE]
                             ↓
User must ask: "Is it done?"
                             ↓
                    Claude checks and responds

Proposed Solution: Event Push API

Enable external processes to push events into active Claude sessions, triggering Claude to respond automatically.

Desired Flow

User prompts Claude → Claude starts background process
                             ↓
                      Process runs (5 min)
                             ↓
                      Process completes ✓
                             ↓
                   [PUSH EVENT TO CLAUDE]
                             ↓
            Claude automatically responds with:
            - Process completion summary
            - Results/output
            - Followup prompt for next action

Architecture Design

Option A: Session-Based Webhook API

┌──────────────────────────────────────────────────────┐
│              Claude Code Session                      │
│  ┌────────────────────────────────────────────────┐  │
│  │  Active Conversation Thread                    │  │
│  │  Session ID: sess_abc123                       │  │
│  └────────────────────────────────────────────────┘  │
│                       ▲                               │
│                       │                               │
│              Event Ingestion Endpoint                 │
│       POST /api/sessions/{session_id}/events          │
└───────────────────────│──────────────────────────────┘
                        │
                        │ HTTPS POST
                        │ {
                        │   "event": "task_complete",
                        │   "data": {...},
                        │   "auth_token": "..."
                        │ }
                        │
┌───────────────────────┴──────────────────────────────┐
│         Background Process / MCP Server              │
│  - Long-running computation                          │
│  - External API polling                              │
│  - File system watcher                               │
│  - Cron job completion                               │
└──────────────────────────────────────────────────────┘

Pros:

• Direct push mechanism
• Real-time notifications
• No polling overhead
• Clean separation of concerns

Cons:

• Requires Claude to expose HTTP endpoint
• Security/authentication complexity
• Session management overhead
• Network configuration (firewall, ports)

Option B: Message Queue via MCP Extension

┌──────────────────────────────────────────────────────┐
│              Claude Code Session                      │
│  ┌────────────────────────────────────────────────┐  │
│  │  Active Conversation                           │  │
│  └────────────────────────────────────────────────┘  │
│                       ▲                               │
│                       │ Poll every N seconds          │
│  ┌────────────────────┴────────────────────────────┐ │
│  │  MCP Event Queue Server                         │ │
│  │  - In-memory event queue                        │ │
│  │  - Session-aware routing                        │ │
│  └────────────────────▲────────────────────────────┘ │
└────────────────────────┼─────────────────────────────┘
                         │
                         │ Write event
                         │ mcp_event_queue.push({
                         │   session: "sess_abc123",
                         │   event: {...}
                         │ })
                         │
┌────────────────────────┴─────────────────────────────┐
│         Background Process / MCP Tool                │
│  - Has access to MCP event queue                    │
│  - Writes events to shared queue                    │
└──────────────────────────────────────────────────────┘

Pros:

• No network exposure needed
• Works with existing MCP architecture
• Simpler authentication (shared memory/IPC)
• Easier to implement

Cons:

• Polling introduces latency
• Requires special MCP server implementation
• Session ID must be passed to background process

Option C: File-Based Event Watchers

┌──────────────────────────────────────────────────────┐
│              Claude Code Session                      │
│  ┌────────────────────────────────────────────────┐  │
│  │  Active Conversation                           │  │
│  │  Auto-triggered by file change hook            │  │
│  └────────────────────────────────────────────────┘  │
│                       ▲                               │
│                       │                               │
│  ┌────────────────────┴────────────────────────────┐ │
│  │  File System Watcher (New Hook)                 │ │
│  │  - Watches: ~/.claude/events/{session_id}/      │ │
│  │  - On change: inject event as user message      │ │
│  └────────────────────▲────────────────────────────┘ │
└────────────────────────┼─────────────────────────────┘
                         │
                         │ Write file
                         │ echo '{"status":"done"}' >
                         │   ~/.claude/events/sess_abc/event.json
                         │
┌────────────────────────┴─────────────────────────────┐
│         Background Process                           │
│  - Knows session ID from environment                 │
│  - Writes completion event to session dir            │
└──────────────────────────────────────────────────────┘

Pros:

• Simplest implementation
• No network/IPC complexity
• Works across all platforms
• Easy to debug (just check files)

Cons:

• File system overhead
• Polling still needed for file watching
• Cleanup required (stale event files)

Detailed Feature Requirements

1. Session Identity

Background processes need to know which Claude session to notify:

# When Claude spawns background process, pass session ID
export CLAUDE_SESSION_ID="sess_abc123"
python background_task.py &

2. Event Schema

Standardized event format:

{
  "session_id": "sess_abc123",
  "event_type": "task_complete | error | progress_update | user_input_needed",
  "timestamp": "2025-11-20T02:00:00Z",
  "source": "background_process_name",
  "data": {
    "message": "Processing complete: analyzed 10,000 records",
    "results": {...},
    "next_action_prompt": "Would you like me to generate the report now?"
  },
  "priority": "high | normal | low"
}

3. Security & Authentication

Events must be authenticated to prevent:

• Unauthorized event injection
• Session hijacking
• Malicious prompt injection

Options:

• Session-specific auth tokens
• Process signature verification
• Filesystem permissions (for file-based approach)

4. Claude's Response Behavior

When event is received:

┌─────────────────────────────────────────────┐
│ Event Received                              │
│ Type: task_complete                         │
│ Source: data_analysis_job                   │
└─────────────────────────────────────────────┘
           ▼
┌─────────────────────────────────────────────┐
│ Claude Generates Response                   │
│ - "Your data analysis has completed!"       │
│ - Summary of results from event.data        │
│ - Followup question/prompt                  │
└─────────────────────────────────────────────┘
           ▼
┌─────────────────────────────────────────────┐
│ Displayed to User (Auto-expand)             │
│ User sees Claude's proactive response       │
└─────────────────────────────────────────────┘

Use Cases

1. Long-Running Data Analysis

# Claude runs analysis
claude: "Starting analysis of 1M records, this will take ~10 minutes"
bash: python analyze_data.py &

# 10 minutes later, process pushes event
# Claude automatically responds
claude: "✓ Analysis complete! Found 3 anomalies and 2 trends.
        Would you like me to generate visualizations?"

2. External API Polling

# Claude sets up monitoring
claude: "I've started monitoring the deployment status"

# When deployment completes, monitoring script notifies
claude: "Your deployment to production is live!
        Status: ✓ All health checks passed
        What would you like to do next?"

3. File System Watching

# Claude starts file watcher
claude: "Watching for new CSV files in /data/incoming"

# When new file appears
claude: "New file detected: sales_2025-11-20.csv
        Shall I process this file using our standard pipeline?"

4. Scheduled Task Completion

# Claude schedules daily report
claude: "I've scheduled the daily report to run at 8am"

# Next morning at 8am
claude: "Your daily report is ready!
        Key metrics: Revenue +15%, New users: 247
        [View Full Report]"

Implementation Recommendations

Phase 1: File-Based Events (Simplest)

1. Add new hook type: OnExternalEvent
2. File watcher monitors ~/.claude/events/{session_id}/
3. Background processes write JSON events to watched directory
4. Claude reads event and generates response

Implementation effort: Low
Risk: Low
User value: High

Phase 2: MCP Event Queue

1. Create official MCP Event Queue server
2. Background processes use MCP tools to push events
3. Claude polls event queue via MCP
4. More robust than filesystem approach

Implementation effort: Medium
Risk: Medium
User value: High

Phase 3: Webhook API (Full Solution)

1. Claude exposes local webhook endpoint
2. Session-based authentication
3. Background processes POST events
4. Real-time event injection

Implementation effort: High
Risk: High (security, networking)
User value: Very High

Open Questions

1. Session Lifecycle: How long should sessions remain "subscribable" to events?
2. Event Persistence: Should undelivered events be queued or dropped?
3. Rate Limiting: How to prevent event spam?
4. Multi-modal Events: Should events support images, files, etc.?
5. User Control: Should users approve event sources? (Similar to MCP server approval)

Alternatives Considered

Status Quo: Manual Polling

User: "Is the analysis done yet?"
Claude: [checks] "Not yet, still processing..."

# 5 minutes later
User: "How about now?"
Claude: [checks] "Yes! Here are the results..."

Why inadequate: Poor UX, breaks conversation flow, wastes user time

Persistent MCP Servers with Status Endpoints

Background process updates status in MCP server, Claude periodically queries.

Why inadequate: Still requires polling, no proactive notification

Related Features

This would complement existing Claude Code features:

• Hooks system: Events could trigger hooks
• MCP servers: Natural integration point for event sources
• Background processes: Enables truly async workflows

Success Metrics

• Background processes can reliably notify Claude sessions
• Latency from event → Claude response < 5 seconds
• Zero false triggers (no unauthorized event injection)
• User satisfaction: "Claude proactively follows up"

References

• Current hooks system: .claude/settings.local.json → hooks
• MCP specification: https://modelcontextprotocol.io
• Related issue: [Link to any existing GitHub issues]

---

Recommended Approach: Start with Phase 1 (File-Based Events) for rapid prototyping and validation, then graduate to Phase 2 (MCP Event Queue) for production use.