feat(cursor): Add real-time capture via ~/.cursor/hooks.json

[aktasbatuhan]

Background

PR #113 added Cursor adapter support by reading the SQLite chat store (globalStorage/state.vscdb). This works for retroactive discovery but doesn't provide real-time session capture.

Goal

Add real-time capture for Cursor sessions so curation can fire without waiting for the next scan, matching the experience for Claude Code and Codex.

Approach (corrected)

Cursor does have a hooks mechanism (https://cursor.com/docs/hooks, v1.7+), but it is NOT a drop-in equivalent of Claude Code's transcript_path. The hooks are event-based and fire-and-forget: sessionStart, beforeShellExecution, afterFileEdit, stop, etc. There is no single JSONL transcript file emitted that we can tail the way we do for the JSONL agents.

So real-time capture here likely means one of:

• a stop / sessionEnd hook that triggers a re-scan of the just-finished composer in state.vscdb (cheapest, reuses the existing SQLite adapter), or
• reconstructing a transcript from the event stream itself (more work, and the events carry less than the store does).

Worth scoping which one is actually worth it before committing. The store reader from #113 already covers the data; the open question is purely latency.

Acceptance Criteria

• Document the actual ~/.cursor/hooks.json event format and what each event carries
• Decide: re-scan-on-stop vs reconstruct-from-events (lean re-scan unless events add something the store lacks)
• Wire the chosen path into the existing Cursor adapter / scan pipeline
• Add setup docs for enabling the hook
• Test with a real Cursor session

/cc @goktugecertastan-cyber - you mentioned wiring this as a follow-up. Heads up that the hooks look event-based rather than a transcript file, so a stop-hook that re-scans the store may be the simplest route. Curious if that matches what you saw.

[Necmttn]

Cursor hooks seem better as dirty-session markers than as the transcript source.

On stop or file/tool events, record session id if available, project root, event timestamp, and a dirty flag. Then let the existing SQLite/JSONL scanner replay idempotently from authoritative stores, deduping by session UUID/path instead of reconstructing history from lossy hook events.

---

Generated with ax.

[aktasbatuhan]

This lines up with where the issue was already leaning, and the dirty-marker framing makes it cleaner. Locking the design:

• The stop/event hooks write a dirty record: session id (when present), project root, event timestamp, dirty flag. That is all they do. No transcript reconstruction.
• The existing state.vscdb reader stays the single source of truth. On a dirty signal it replays idempotently and dedupes by session UUID + path, so a missed or doubled hook event costs nothing.
• That keeps the lossy event stream out of the data path entirely. Hooks only answer "which composer changed and when," the store answers "what happened."

Net effect on the acceptance criteria: we can drop "reconstruct-from-events" as a real option and treat it as the rejected alternative. The work becomes: document the hook event shape, add a thin dirty-record writer wired to stop (and maybe afterFileEdit), and have the scanner consume dirty records instead of doing a full cold scan. Latency goes from "next scheduled scan" to "moment the session stops," reusing everything #113 already shipped.