From ddc6f3b4e7af187e5d901dcc223a7f1c9976b0ba Mon Sep 17 00:00:00 2001
From: Lukas May <lukas.may@carealytix.com>
Date: Fri, 30 Jan 2026 19:59:37 +0100
Subject: [PATCH] feat(04-02): add agent lifecycle events to events module

- AgentSpawnedEvent for new agent creation
- AgentStoppedEvent with reason (user_requested, task_complete, error, waiting_for_input)
- AgentCrashedEvent for unexpected failures
- AgentResumedEvent for session resumption
- AgentWaitingEvent when agent pauses on AskUserQuestion
- Updated DomainEventMap union with all agent events
---
 src/events/index.ts |  5 ++++
 src/events/types.ts | 62 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/src/events/index.ts b/src/events/index.ts
index 0499377..8904ed8 100644
--- a/src/events/index.ts
+++ b/src/events/index.ts
@@ -20,6 +20,11 @@ export type {
   WorktreeRemovedEvent,
   WorktreeMergedEvent,
   WorktreeConflictEvent,
+  AgentSpawnedEvent,
+  AgentStoppedEvent,
+  AgentCrashedEvent,
+  AgentResumedEvent,
+  AgentWaitingEvent,
   DomainEventMap,
   DomainEventType,
 } from './types.js';
diff --git a/src/events/types.ts b/src/events/types.ts
index f5a70c5..d245b17 100644
--- a/src/events/types.ts
+++ b/src/events/types.ts
@@ -132,6 +132,61 @@ export interface WorktreeConflictEvent extends DomainEvent {
   };
 }
 
+/**
+ * Agent Events
+ */
+
+export interface AgentSpawnedEvent extends DomainEvent {
+  type: 'agent:spawned';
+  payload: {
+    agentId: string;
+    name: string;
+    taskId: string;
+    worktreeId: string;
+  };
+}
+
+export interface AgentStoppedEvent extends DomainEvent {
+  type: 'agent:stopped';
+  payload: {
+    agentId: string;
+    name: string;
+    taskId: string;
+    reason: 'user_requested' | 'task_complete' | 'error' | 'waiting_for_input';
+  };
+}
+
+export interface AgentCrashedEvent extends DomainEvent {
+  type: 'agent:crashed';
+  payload: {
+    agentId: string;
+    name: string;
+    taskId: string;
+    error: string;
+  };
+}
+
+export interface AgentResumedEvent extends DomainEvent {
+  type: 'agent:resumed';
+  payload: {
+    agentId: string;
+    name: string;
+    taskId: string;
+    sessionId: string;
+  };
+}
+
+export interface AgentWaitingEvent extends DomainEvent {
+  type: 'agent:waiting';
+  payload: {
+    agentId: string;
+    name: string;
+    taskId: string;
+    sessionId: string;
+    question: string;  // The question being asked
+  };
+}
+
 /**
  * Union of all domain events - enables type-safe event handling
  */
@@ -145,7 +200,12 @@ export type DomainEventMap =
   | WorktreeCreatedEvent
   | WorktreeRemovedEvent
   | WorktreeMergedEvent
-  | WorktreeConflictEvent;
+  | WorktreeConflictEvent
+  | AgentSpawnedEvent
+  | AgentStoppedEvent
+  | AgentCrashedEvent
+  | AgentResumedEvent
+  | AgentWaitingEvent;
 
 /**
  * Event type literal union for type checking