Plugin event reference

Every event a [[events]] hook can subscribe to, with its exact trigger semantics, detail fields, and a real envelope. The one-line catalog lives in Writing Rove plugins; this page is the per-event contract.

Ground rules that apply to every event here:

• Async observers. Your command runs after the fact; exit code and output never block or change what happened.
• The envelope arrives as JSON in ROVE_PLUGIN_EVENT_JSON (SDK: pluginEvent()), with ROVE_PLUGIN_EVENT, ROVE_PLUGIN_TASK_ID, and ROVE_PLUGIN_TASK_TITLE as plain-var shortcuts:

{
  "event": "…",                   // the subscribed name
  "taskId": "01M0…",              // when the event mapped to a task
  "task": {                       // task context at emit time, when known
    "id": "01M0…", "title": "…", "repo": "/path", "branch": "…",
    "worktreePath": "/path", "vendor": "claude", "status": "in_progress"
  },
  "vendor": "claude",             // agent-layer events: which engine reported
  "tabId": "tab-1",               // when the session is a Rove terminal tab
  "sessionId": "…",               // the engine's own session id, when known
  "detail": { /* per-event, documented below */ },
  "at": 1690000000000             // epoch ms at emit
}

• Optional means absent, never null-filled. A field listed below can be missing whenever its source didn't know it, so validate what you read.
• Engine support marks: C Claude Code · X Codex · K Kimi Code · P Pi · O OMP (the pi coding agent's fork — same adapter, same hook file, so the two only differ where noted). Product-layer events are engine-independent.

Task lifecycle

Sourced from field-level diffs of consecutive task-index snapshots, so every mutation path fires them: RPC handlers, land, the git worktree remove sweep, adopt flows. The first snapshot after a daemon start is baseline: pre-existing tasks never re-fire.

task.created / task.deleted

A task appeared in / disappeared from the index. task carries the context (on delete: the last known state). A task adopted WITH a worktree fires task.created and worktree.created in the same batch, in that order.

task.changed

Any watched field changed. Excluded on purpose: position (board-drag noise), updatedAt/createdAt (ride every change), quotaResume (the quota.* events cover it), deletion (task.deleted covers it), and prStatus (its own event below).

{ "event": "task.changed", "taskId": "01M0…",
  "detail": { "fields": ["title", "pinned"],
              "from": { "title": "scratch", "pinned": false },
              "to":   { "title": "fix flaky test", "pinned": true } } }

task.landed

The task's branch merged into its base repo. This is the one task event still emitted by its handler, because the merge detail never reaches the snapshot.

task.pr-changed

The task's PR status changed. Compared with the PR poller's own semantics: lastCheckedAt/lastError churn does not count as change.

Typical use: toast when to.checkState flips to failing, or set the task's status to done when to.lifecycle becomes "merged".

worktree.created

A managed task's worktree materialized: lazy ensure on first open, adopt of an external worktree, or scratch-adopt. Fires once per task (empty → set path transition); a worktree MOVE is a task.changed on worktreePath.

Issues, notes, delivery, attention

issue.changed

A daemon-tracker issue mutated.

note.filed

A session filed a field note (rove api note).

message.delivered

Text was dispatched toward a task's live session (rove api dispatch, or a note relay). This reports reach, not receipt: delivery is broadcast-based, so the daemon cannot observe the paste itself.

attention.handled

The human resolved an attention-inbox episode.

Automations and quota

automation.dispatched / automation.skipped / automation.failed

One scheduled-automation run finished with that outcome. All three share one detail shape:

automation.dispatched covers dispatched and revived runs. automation.failed covers dispatch_failed runs. The remaining statuses, including skipped_unavailable, emit automation.skipped. skipped_cancelled means the routine was disabled, edited, deleted or stopped before handoff.

taskId identifies the created, standing or explicitly bound target when known, including failed attempts. Its presence does not prove task creation or delivery. Scheduled occurrences are claimed before dispatch and are not automatically replayed after restart; a crash between claim, delivery and receipt persistence can lose an occurrence or receipt. These events do not promise exactly-once delivery.

quota.exhausted

A rate-limited turn armed the auto-resume schedule.

quota.resumed

The resume schedule came due and the continue prompt was sent.

Sessions and crashes

session.start / session.end · C, X (start only), K, P, O

The engine's own session lifecycle, from its hooks. session.end never fires on a crash. That is what session.exited is for.

session.exited

A hosted PTY child died abnormally (non-zero exit or a signal; clean exits are never recorded). Watched off the PTY host's durable death records, so it fires even though the host is a separate process. This is the crash signal.

{ "event": "session.exited", "taskId": "01M0…",
  "detail": { "key": "01M0…::tab-1", "tabId": "tab-1", "pid": 4242,
              "code": 1, "signal": null, "exitedAt": "2026-08-26T…",
              "tail": ["Error: ENOMEM", "  at spawn (…)"] } }

Turns and activity

Two views of the same engine, at different granularities. Activity states (agent.*) are the reduced per-task+tab badge states, deduped, so you see transitions, not every report. Turn edges (turn.*) are one event per hook report, unreduced.

agent.running / agent.idle / agent.turn-complete / agent.permission-needed / agent.rate-limited / agent.error

Activity-state transitions. Keyed per task+tab: the same state twice in a row is suppressed. tabId is present when the reporting session identifies its tab. No detail beyond the envelope.

turn.prompt · C, X, K, P, O

A user prompt entered the engine (turn-start). One per turn.

turn.complete · C, X, K, P, O

The turn finished. When the engine's transcript yielded telemetry, detail.turn carries it (absent otherwise, never fabricated):

{ "event": "turn.complete", "taskId": "01M0…", "vendor": "claude",
  "detail": { "turn": { "id": "msg_…", "model": "claude-sonnet-5",
                        "usage": { "input_tokens": 1200, "output_tokens": 340 },
                        "startedAt": 1690000000000, "endedAt": 1690000042000 } } }

turn.failed · C, K, P, O

On pi and OMP the failure text comes from the assistant message that failed (stopReason: "error") and, on OMP, from a final auto_retry_end — a retry that RECOVERED reports nothing.

A rate_limit failure also arms auto-resume, so expect a quota.exhausted right after when the quota probe finds a reset time.

turn.interrupted · C (emulated), X (emulated), K (native), P, O (native)

The user interrupted the turn. Exists because Kimi fires Interrupt INSTEAD of Stop. Without this verb an interrupted Kimi turn would strand in running.

Kimi, pi and OMP report this natively (pi and OMP read it off the assistant message that was aborted). On Claude and Codex the event is emulated by the attached TUI, which watches the session's terminal title for the engine dropping back to rest and reports the interrupt itself — so on those two engines it behaves like a UI moment: no attached TUI, no event. A headless daemon, a rove api driver, or a plugin that only ever sees background sessions will never observe turn.interrupted on C or X. Subscribe to agent.idle as well if you need the interrupt to be noticed without a TUI.

Tools: the high-volume family

tool.pre / tool.post · C, X, K, P, O · tool.failed · C, K, P, O

One event per engine tool call, before/after. Volume-gated install: the underlying engine hooks are written into engine config only while some enabled plugin subscribes to a tool.* event; enabling/disabling such a plugin takes effect at the next Rove start.

Expect real volume: a busy session fires dozens per minute. Keep the hook sub-second and silent.

Attention (engine blocked on a human)

attention.permission · C, K, O · attention.question · C, O

OMP reports both from its own events: tool_approval_requested for the native approval prompt, and its question tool (ask). Pi has no approval prompt, so it has no permission source — only its screen rules.

The engine stopped and is waiting. One awaiting-input report splits on why:

Context compaction

context.pre-compact / context.post-compact · C, X, K, P, O

Subagents

subagent.start / subagent.stop · C, K

A nested agent began/ended under the session.

UI moments

Reported by the attached TUI; they fire only while a TUI is attached.

task.opened / project.opened

The user selected/entered a task (or a project's main row). No detail.

file.will-open / file.opened / file.closed

Files-pane opens, before and after, and the editor tab leaving the strip.

will- precedes the action but cannot block it. Observers only.

tab.opened / tab.closed

A workspace terminal tab appeared/went away. Mount-time restores don't fire.

Plugin registry

plugin.enabled / plugin.disabled

YOUR plugin's registry entry transitioned, delivered only to the affected plugin, so subscribing is how you get lifecycle callbacks without polling. plugin.disabled is the last event a disabled plugin's hooks receive.

What is NOT an event

Threshold policies ("worktree dirtier than N", "usage above X%") stay out of the catalog: they are plugin judgment. Subscribe to the daemon's broadcast channels over the raw socket (SDK: RoveSocket.subscribe, catalog: DAEMON_CHANNELS in the contract module) and decide yourself: worktree.changes and usage.snapshot carry the state these policies need. If a MOMENT you need is genuinely missing, ask via rove feedback; the plumbing makes additions cheap.