perf(hooks): add subscription-based event filtering to reduce hot-path dispatch overhead

[coleleavitt]

Summary

• Adds subscription-based event filtering to the hook dispatcher so hooks only execute on events they care about
• Reduces hot-path dispatch overhead during LLM streaming from ~2,100 async dispatches/sec to only the hooks that subscribed to delta events
• Maintains full backward compatibility — hooks without subscriptions receive all events as before

Problem

During LLM streaming, the processor emits ~10 PartDelta events/second. Each event dispatches to ALL 21 hooks sequentially, even though most hooks don't handle delta events. This creates ~2,100 unnecessary async dispatches/second, generating excessive garbage that triggers GC pressure and contributes to TUI freeze.

Solution

Hooks can now declare which event types they care about via a subscriptions array:

{
  name: "my-hook",
  subscriptions: ["session.completed", "message.completed"],
  execute: async (event) => { /* only called for subscribed events */ }
}

The dispatcher builds a subscription map at initialization and routes events only to subscribed hooks. Hooks without subscriptions are treated as "subscribe to all" for backward compatibility.

Changes

• src/plugin/event.ts: Added Subscription type, subscriptions field to Hook, subscription map building in create(), filtered dispatch in dispatch()

Verification

• bun x tsc --noEmit passes clean

---

Summary by cubic

Adds subscription-based event filtering so only subscribed hooks run. This reduces hot-path dispatch during LLM streaming and lowers GC pressure, and fixes lifecycle subscriptions and fire-and-forget error handling.

• Refactors

  • Add HOOK_SUBSCRIPTIONS and build a subscription map at init; unspecified hooks default to "*".
  • Replace sequential all-hooks dispatch with filtered routing by event type.
  • Keep critical hooks awaited (claudeCodeHooks, stopContinuationGuard, writeExistingFileGuard); others fire-and-forget with error logging. For message.part.delta, 19 of 21 hooks are skipped.

• Bug Fixes

  • Add missing session.deleted and session.compacted subscriptions to lifecycle and cleanup hooks.
  • Wrap fire-and-forget invokes in Promise.resolve().then(...) to catch sync throws.

^{Written for commit cae1645. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 1 file

Confidence score: 2/5

• Stateful hooks no longer receive session.deleted events in src/plugin/event.ts, which is a concrete regression that can leak resources during cleanup
• Opencode compatibility is broken because session.compacted is filtered out by the new subscription map, so compaction handlers stop running
• Given both issues are high severity and user-facing, the merge risk is high despite limited file scope
• Pay close attention to src/plugin/event.ts - event filtering removes session.deleted and session.compacted delivery to hooks.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin/event.ts">

<violation number="1" location="src/plugin/event.ts:140">
P1: Custom agent: **Opencode Compatibility**

Opencode compatibility break: `session.compacted` is filtered out by the new subscription map, so hooks that implement compaction handling no longer receive that OpenCode event.</violation>

<violation number="2" location="src/plugin/event.ts:159">
P1: Stateful hooks are filtered from receiving session.deleted events they need for cleanup, causing resource leaks</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[code-yeongyu]

[sisyphus-bot]

PR Assessment: Performance Optimization with Event Filtering

Type: Performance enhancement (not a bugfix)
Risk Level: MEDIUM (architectural change to event dispatch)
Recommendation: Needs human review - DO NOT auto-merge

Summary

This PR introduces subscription-based event filtering to reduce hot-path dispatch overhead during LLM streaming. Instead of dispatching all events to all 21 hooks sequentially, hooks now only receive events they've subscribed to.

Key Changes

• Added HOOK_SUBSCRIPTIONS map defining which event types each hook cares about
• Hooks without explicit subscriptions default to "*" (receive all events) for backward compatibility
• Critical hooks (claudeCodeHooks, stopContinuationGuard, writeExistingFileGuard) are awaited; others use fire-and-forget
• Expected reduction: ~2,100 async dispatches/sec → only subscribed hooks

Cubic AI Review Findings

Cubic raised 2 P1 concerns:

1. Stateful hooks not receiving session.deleted - Potential resource leaks
2. session.compacted filtered out - OpenCode compatibility break

Analysis of findings:
Upon reviewing the current code:

• SESSION_LIFECYCLE array includes both session.deleted and session.compacted
• compactionTodoPreserver explicitly subscribes to both events
• stopContinuationGuard uses SESSION_LIFECYCLE which has both events

The Cubic findings may refer to an earlier commit state. The PR description mentions "fixes lifecycle subscriptions" suggesting these were addressed.

Merge Readiness Check

Condition	Status
CI passing	✅ All 7 checks passed
Mergeable state	✅ MERGEABLE
Draft	✅ Not draft
Review approval	❌ NOT APPROVED
Bugfix with clear fix	❌ Performance optimization, not bugfix

Blockers to Auto-Merge

1. No human approval - Review decision is empty
2. Not a bugfix - This is an architectural/performance change
3. AI reviewer flagged concerns - Cubic identified potential issues (may be resolved)

Suggested Action

Needs human maintainer review. This is a core architectural change to the event dispatch system. While CI passes and the code looks correct, the performance optimization touches critical hot-path code that affects all hook execution.

Please have a maintainer:

1. Verify the Cubic findings are addressed in the current commit
2. Review the subscription assignments for correctness
3. Consider load testing to validate the performance gains

---

Assessment by sisyphus-bot

[code-yeongyu]

[sisyphus-bot]

PR sweep first-pass triage on dev.

• Author: coleleavitt
• Title: perf(hooks): add subscription-based event filtering to reduce hot-path dispatch overhead
• Closing issues: none detected
• Review decision: none yet
• Mergeable state: CONFLICTING (rebase needed)
• CI status: green / no failing checks

Needs rebase + review. Please rebase onto current dev first; then a review can land cleanly.

Assigning code-yeongyu so the maintainer can prioritize a focused review of this PR. If the linked issue above has been triaged, the verdict there is the authoritative direction for this change.

[code-yeongyu]

[sisyphus-bot] Hi coleleavitt. 🙏 Thanks for the subscription-based event filtering perf work.

Picking this back up from the 5/16 triage. The PR is small (71/21 in 1 file) and shows CONFLICTING against current dev. The hook-dispatcher event-filtering has been touched on dev.

Could you rebase against current dev and force-push? Perf changes in the hook layer are sensitive (every event-type filter touches every hook in the 5-tier composition). After rebase, please add a brief benchmark or before/after numbers showing the reduction in hook invocations under typical workloads. Once that's in I'll loop a maintainer in for the focused review.

[coleleavitt]

no longer contributing atm; stale PR and can be rebased if desired