[FEATURE] Background polling hook for async external event injection

Summary

Request for a new hook type or settings-level configuration that allows Claude Code to periodically check for external events (e.g., messages from other AI instances, CI/CD notifications, monitoring alerts) and inject them into the active conversation context — even when the AI is idle.

Problem

The current hook system is reactive: hooks fire on specific events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, Notification, SubagentStop). When Claude Code is idle (no tool calls, no user prompts), no hooks fire and external messages accumulate unread.

Real-world use case: We run a multi-machine SEIF protocol where two Claude Code instances (Mac Air + Mac Mini) communicate via a WebSocket hub. Messages arrive in an inbox directory. We use PreToolUse/UserPromptSubmit/Stop hooks to drain the inbox — this works during active work but fails during idle periods. The human must manually send a prompt to trigger message delivery, defeating the purpose of autonomous AI-to-AI coordination.

Proposed Solution

A settings-level configuration like:

{
  "backgroundPolling": {
    "enabled": true,
    "intervalSeconds": 60,
    "command": "/path/to/check-inbox.sh",
    "injectIfOutput": true
  }
}

Or alternatively, an OnExternalEvent hook type that fires periodically (configurable interval) regardless of user/AI activity.

Behavior

• Runs the command every N seconds in the background
• If the command produces stdout, inject it into the conversation as a system message (similar to hook output)
• If no output, no injection (zero cost)
• Respects session lifecycle (starts on SessionStart, stops on SessionEnd)
• Budget: command should complete in <500ms (fast-path when no events)

Alternatives Considered

1. PreToolUse + UserPromptSubmit + Stop + Notification hooks: Already implemented. Covers ~95% of cases but fails during idle.
2. Bash run_in_background polling: Session-bound, cannot inject into context asynchronously.
3. /loop skill: Requires manual invocation by user.
4. File watching: Claude Code doesn't watch files.
5. statusLine refreshInterval: Exists but only for status display, not context injection.

Impact

This would enable:

• Multi-AI orchestration without human relay
• CI/CD notification injection during long builds
• External monitoring alerts during active sessions
• Any async event-driven workflow where the AI needs to react to external signals

🤖 Generated with Claude Code