Add get_events on every prompt and session start for maximum synchronization

[evansenter]

Summary

Add get_events calls via hooks at two lifecycle points:

1. UserPromptSubmit - Check for new events before processing every user prompt
2. SessionStart - Catch up on events that occurred since last session

This enables maximum synchronization between parallel Claude Code sessions.

Problem / Motivation

Currently, event bus events are only checked when explicitly requested via /session-status or /status-report commands. Long-running sessions can miss important messages from parallel workers (e.g., "auth feature ready for integration", "CI failed on shared branch") for extended periods.

For true multi-session coordination, sessions should be aware of events continuously, not just when they remember to check.

Context

• Discovered during: Discussion of event bus integration opportunities
• Relevant files: home/.claude/hooks/session-start.sh, home/.claude/settings.json
• Benchmark: event-bus-cli events takes ~250-300ms (including Python startup + HTTP)

Investigation Results

Hook Support ✅

• Claude Code supports UserPromptSubmit hooks
• Hook stdout is added as context for Claude (with exit code 0)
• Hooks cannot call MCP tools directly, but can call CLI tools

CLI Support ✅

• event-bus-cli events --since <id> enables incremental fetching
• Output is human-readable and can be filtered

Proposed Solution

1. Create prompt-events.sh hook

#!/bin/bash
# Check for new events on every prompt

STATE_FILE="${XDG_STATE_HOME:-$HOME/.local/state}/claude/last_event_id"
mkdir -p "$(dirname "$STATE_FILE")"
LAST_ID=$(cat "$STATE_FILE" 2>/dev/null || echo "0")

# Get events since last check, filter noise
EVENTS=$(event-bus-cli events --since "$LAST_ID" 2>/dev/null | \
  grep -v 'session_registered\|session_unregistered')

if [[ -n "$EVENTS" ]]; then
  echo "<event-bus-updates>"
  echo "$EVENTS"
  echo "</event-bus-updates>"
  
  # Save latest ID for next check
  NEW_ID=$(echo "$EVENTS" | tail -1 | grep -o '^\[[0-9]*\]' | tr -d '[]')
  [[ -n "$NEW_ID" ]] && echo "$NEW_ID" > "$STATE_FILE"
fi

exit 0

2. Update session-start.sh

Add event fetching alongside registration:

# After registration output...

# Also catch up on recent events
EVENTS=$(event-bus-cli events --since 0 --limit 10 2>/dev/null | \
  grep -v 'session_registered\|session_unregistered' | tail -5)

if [[ -n "$EVENTS" ]]; then
  echo "<recent-events>"
  echo "$EVENTS"
  echo "</recent-events>"
fi

3. Add to settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/prompt-events.sh" }]
      }
    ]
  }
}

Assumptions

Assumption	Confidence	Impact if Wrong
250-300ms latency is acceptable on every prompt	Medium	Noticeable UX degradation
Most prompts have no new events	High	Output would be noisy if events are frequent
event-bus-cli will be installed	High	Falls back gracefully if not present
Filtering session_registered/unregistered reduces noise sufficiently	Medium	May need more sophisticated filtering

Trade-offs

Pros:

• Maximum awareness of cross-session events
• Never miss a direct message or important broadcast
• Heartbeat-like behavior keeps session alive in event bus

Cons:

• ~250-300ms latency on every prompt
• Most checks return nothing (wasted work)
• Requires event-bus-cli to be installed

Actionable Requirements

#	Requirement	Owner	Blocked By
1	Create prompt-events.sh hook	Claude	None
2	Update session-start.sh to fetch recent events	Claude	None
3	Add UserPromptSubmit hook to settings.json	Claude	#1
4	Add hook to bootstrap.sh symlink list	Claude	#1
5	Test with parallel sessions	Claude	#1, #2, #3
6	Update CLAUDE.md documentation	Claude	#5

Implementation Checklist

• Create home/.claude/hooks/prompt-events.sh
• Update home/.claude/hooks/session-start.sh to include event catch-up
• Update home/.claude/settings.json with UserPromptSubmit hook
• Ensure bootstrap.sh symlinks the new hook
• Test: Start two sessions, broadcast from one, verify other sees it on next prompt
• Document in CLAUDE.md Event Bus section

Open Questions

1. Should we add a timeout to prevent slow event-bus-cli from blocking prompts?
2. Should filtering be more sophisticated (e.g., only show repo-relevant events)?
3. Should there be a way to disable this for performance-sensitive work?

[evansenter]

Upstream Dependency

Created claude-event-bus#25 with feature requests to make event-bus-cli more ergonomic for hook-based polling:

• --json - Machine-parseable output
• --exclude-types - Filter out noise events
• --limit - Cap results
• --timeout - Prevent blocking
• --track-state - Auto-persist last_seen_id

Implementation can proceed without these (using grep/regex workarounds), but the CLI enhancements would make the hooks cleaner and more reliable.