@desplega.ai/agent-swarm 1.102.0 → 1.103.0

package/dist/{lead-5fgqwe13.js → lead-7mcxedkc.js}

@@ -1,13 +1,13 @@
 import {
   runAgent
-} from "./cli-vgck9mqq.js";
+} from "./cli-yeemwevj.js";
 import"./cli-wjyyv518.js";
-import"./cli-axtg1zaa.js";
+import"./cli-khe4x17a.js";
 import"./cli-p03mawph.js";
 import"./cli-4wmnp8q3.js";
-import"./cli-s8jw5bmg.js";
-import"./cli-7xdq3jg3.js";
-import"./cli-g5px3d7x.js";
+import"./cli-yp2krx5r.js";
+import"./cli-92fqyjcv.js";
+import"./cli-2957pqpj.js";
 import"./cli-tyfxrrdd.js";
 import"./cli-ncg70f07.js";
 import"./cli-yazx6hap.js";
@@ -16,7 +16,7 @@ import"./cli-d6n0thxw.js";
 import"./cli-hx1dcevq.js";
 import {
   getEnabledCapabilities
-} from "./cli-tsz1q7gk.js";
+} from "./cli-2307phk1.js";
 import"./cli-09rxrad0.js";
 import"./cli-dcfyyh3t.js";
 import"./cli-gz9sbyk3.js";
@@ -25,31 +25,31 @@ import"./cli-psrqtw2m.js";
 import"./cli-tng3131n.js";
 import"./cli-zm7njwzd.js";
 import"./cli-0k9dc6ks.js";
-import"./cli-zmf7refz.js";
-import"./cli-xde8vhhp.js";
-import"./cli-stqqf5kh.js";
-import"./cli-k1ghyj8b.js";
-import"./cli-zk4gn40w.js";
+import"./cli-v9283nma.js";
+import"./cli-ksq38x4n.js";
+import"./cli-m8f6qzck.js";
+import"./cli-4fnp2tc3.js";
+import"./cli-8hyv6c2v.js";
 import"./cli-f14fvzag.js";
-import"./cli-qbc6mncp.js";
-import"./cli-2aaa9mqr.js";
-import"./cli-k81y1cjb.js";
+import"./cli-gzepjz54.js";
+import"./cli-fygaw191.js";
+import"./cli-8w95v19d.js";
 import"./cli-fad8m16k.js";
-import"./cli-ap4md0gc.js";
-import"./cli-t2jk33ta.js";
+import"./cli-ns0r7mkr.js";
+import"./cli-rttgde5f.js";
 import"./cli-2deg0cen.js";
-import"./cli-sygq3fhn.js";
+import"./cli-kk51f3tf.js";
 import"./cli-fete3y1e.js";
 import"./cli-b0p7rfnd.js";
-import"./cli-5bqa41fd.js";
+import"./cli-yfwwjeft.js";
 import"./cli-z92pkwzn.js";
 import"./cli-dh55d5fg.js";
-import"./cli-r68m8arr.js";
-import"./cli-d0t4854c.js";
+import"./cli-jt9d9fjw.js";
+import"./cli-fedn86nz.js";
 import"./cli-z2zcxes1.js";
 import"./cli-q21d49ac.js";
 import"./cli-anrj584m.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import"./cli-3pp1362w.js";
 import"./cli-e15jhafb.js";
 import"./cli-9aryf9tv.js";

package/dist/{maintenance-eajx5k1k.js → maintenance-mrzqd53t.js}

@@ -1,12 +1,12 @@
 import {
   reembedAllScripts
-} from "./cli-2aaa9mqr.js";
-import"./cli-k81y1cjb.js";
-import"./cli-d0t4854c.js";
+} from "./cli-fygaw191.js";
+import"./cli-8w95v19d.js";
+import"./cli-fedn86nz.js";
 import"./cli-z2zcxes1.js";
 import"./cli-q21d49ac.js";
 import"./cli-anrj584m.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import"./cli-3pp1362w.js";
 import"./cli-p9swy5t3.js";
 

package/dist/{onboard-jc1w1edg.js → onboard-4dkpv9wa.js}

@@ -3,7 +3,7 @@ import {
   createDefaultMcpJson,
   createDefaultSettingsLocal,
   createHooksConfig
-} from "./cli-fjx4x7nn.js";
+} from "./cli-xmtsan9k.js";
 import {
   require_jsx_dev_runtime
 } from "./cli-6n1nnzm7.js";
@@ -13,7 +13,7 @@ import {
 import {
   init_package,
   package_default
-} from "./cli-hc4rd6sv.js";
+} from "./cli-85pf4z38.js";
 import {
   Box_default,
   Select,

package/dist/{otel-impl-8k375amf.js → otel-impl-jt7gpyp9.js}

@@ -6,7 +6,7 @@ import {
 import {
   init_package,
   package_default
-} from "./cli-hc4rd6sv.js";
+} from "./cli-85pf4z38.js";
 import {
   init_secret_scrubber,
   scrubSecrets

package/dist/{pi-mono-adapter-hf8sw7hs.js → pi-mono-adapter-zf7dt1wg.js}

@@ -29,7 +29,7 @@ import"./cli-4wmnp8q3.js";
 import {
   checkToolLoop,
   clearToolHistory
-} from "./cli-g5px3d7x.js";
+} from "./cli-2957pqpj.js";
 import {
   require_cross_spawn
 } from "./cli-yazx6hap.js";

package/dist/{pricing-refresh-zed6916t.js → pricing-refresh-xqnzh8dt.js}

@@ -2,13 +2,13 @@ import {
   PRICING_REFRESH_INTERVAL_MS,
   refreshPricingFromModelsDev,
   startPricingRefreshLoop
-} from "./cli-xde8vhhp.js";
-import"./cli-stqqf5kh.js";
-import"./cli-d0t4854c.js";
+} from "./cli-ksq38x4n.js";
+import"./cli-m8f6qzck.js";
+import"./cli-fedn86nz.js";
 import"./cli-z2zcxes1.js";
 import"./cli-q21d49ac.js";
 import"./cli-anrj584m.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import"./cli-3pp1362w.js";
 import"./cli-p9swy5t3.js";
 export {

package/dist/{seed-pricing-5805qzkz.js → seed-pricing-56tjm1fj.js}

@@ -1,12 +1,12 @@
 import {
   buildModelsDevSeedRows,
   seedPricingFromModelsDev
-} from "./cli-stqqf5kh.js";
-import"./cli-d0t4854c.js";
+} from "./cli-m8f6qzck.js";
+import"./cli-fedn86nz.js";
 import"./cli-z2zcxes1.js";
 import"./cli-q21d49ac.js";
 import"./cli-anrj584m.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import"./cli-3pp1362w.js";
 import"./cli-p9swy5t3.js";
 export {

package/dist/{setup-wz05vxh0.js → setup-tbwk8j10.js}

@@ -4,14 +4,14 @@ import {
   createDefaultMcpJson,
   createDefaultSettingsLocal,
   createHooksConfig
-} from "./cli-fjx4x7nn.js";
+} from "./cli-xmtsan9k.js";
 import {
   require_jsx_dev_runtime
 } from "./cli-6n1nnzm7.js";
 import {
   getApiKey
 } from "./cli-f14fvzag.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import {
   Box_default,
   Spinner,

package/dist/{worker-j359graf.js → worker-e03za92t.js}

@@ -1,13 +1,13 @@
 import {
   runAgent
-} from "./cli-vgck9mqq.js";
+} from "./cli-yeemwevj.js";
 import"./cli-wjyyv518.js";
-import"./cli-axtg1zaa.js";
+import"./cli-khe4x17a.js";
 import"./cli-p03mawph.js";
 import"./cli-4wmnp8q3.js";
-import"./cli-s8jw5bmg.js";
-import"./cli-7xdq3jg3.js";
-import"./cli-g5px3d7x.js";
+import"./cli-yp2krx5r.js";
+import"./cli-92fqyjcv.js";
+import"./cli-2957pqpj.js";
 import"./cli-tyfxrrdd.js";
 import"./cli-ncg70f07.js";
 import"./cli-yazx6hap.js";
@@ -16,7 +16,7 @@ import"./cli-d6n0thxw.js";
 import"./cli-hx1dcevq.js";
 import {
   getEnabledCapabilities
-} from "./cli-tsz1q7gk.js";
+} from "./cli-2307phk1.js";
 import"./cli-09rxrad0.js";
 import"./cli-dcfyyh3t.js";
 import"./cli-gz9sbyk3.js";
@@ -25,31 +25,31 @@ import"./cli-psrqtw2m.js";
 import"./cli-tng3131n.js";
 import"./cli-zm7njwzd.js";
 import"./cli-0k9dc6ks.js";
-import"./cli-zmf7refz.js";
-import"./cli-xde8vhhp.js";
-import"./cli-stqqf5kh.js";
-import"./cli-k1ghyj8b.js";
-import"./cli-zk4gn40w.js";
+import"./cli-v9283nma.js";
+import"./cli-ksq38x4n.js";
+import"./cli-m8f6qzck.js";
+import"./cli-4fnp2tc3.js";
+import"./cli-8hyv6c2v.js";
 import"./cli-f14fvzag.js";
-import"./cli-qbc6mncp.js";
-import"./cli-2aaa9mqr.js";
-import"./cli-k81y1cjb.js";
+import"./cli-gzepjz54.js";
+import"./cli-fygaw191.js";
+import"./cli-8w95v19d.js";
 import"./cli-fad8m16k.js";
-import"./cli-ap4md0gc.js";
-import"./cli-t2jk33ta.js";
+import"./cli-ns0r7mkr.js";
+import"./cli-rttgde5f.js";
 import"./cli-2deg0cen.js";
-import"./cli-sygq3fhn.js";
+import"./cli-kk51f3tf.js";
 import"./cli-fete3y1e.js";
 import"./cli-b0p7rfnd.js";
-import"./cli-5bqa41fd.js";
+import"./cli-yfwwjeft.js";
 import"./cli-z92pkwzn.js";
 import"./cli-dh55d5fg.js";
-import"./cli-r68m8arr.js";
-import"./cli-d0t4854c.js";
+import"./cli-jt9d9fjw.js";
+import"./cli-fedn86nz.js";
 import"./cli-z2zcxes1.js";
 import"./cli-q21d49ac.js";
 import"./cli-anrj584m.js";
-import"./cli-hc4rd6sv.js";
+import"./cli-85pf4z38.js";
 import"./cli-3pp1362w.js";
 import"./cli-e15jhafb.js";
 import"./cli-9aryf9tv.js";

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.102.0",
+    "version": "1.103.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -6311,6 +6311,18 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "hooks": {
+                      "type": "object",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "default": false
+                        }
+                      },
+                      "default": {
+                        "enabled": false
+                      }
+                    },
                     "guidelines": {
                       "type": [
                         "object",
@@ -6427,6 +6439,18 @@
                   "autoClone": {
                     "type": "boolean"
                   },
+                  "hooks": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "default": false
+                      }
+                    }
+                  },
                   "guidelines": {
                     "type": [
                       "object",
@@ -6500,6 +6524,18 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "hooks": {
+                      "type": "object",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "default": false
+                        }
+                      },
+                      "default": {
+                        "enabled": false
+                      }
+                    },
                     "guidelines": {
                       "type": [
                         "object",
@@ -6724,6 +6760,18 @@
                             "type": "boolean",
                             "default": true
                           },
+                          "hooks": {
+                            "type": "object",
+                            "properties": {
+                              "enabled": {
+                                "type": "boolean",
+                                "default": false
+                              }
+                            },
+                            "default": {
+                              "enabled": false
+                            }
+                          },
                           "guidelines": {
                             "type": [
                               "object",
@@ -6819,6 +6867,15 @@
                   "autoClone": {
                     "type": "boolean"
                   },
+                  "hooks": {
+                    "type": "object",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "default": false
+                      }
+                    }
+                  },
                   "guidelines": {
                     "type": [
                       "object",
@@ -6896,6 +6953,18 @@
                       "type": "boolean",
                       "default": true
                     },
+                    "hooks": {
+                      "type": "object",
+                      "properties": {
+                        "enabled": {
+                          "type": "boolean",
+                          "default": false
+                        }
+                      },
+                      "default": {
+                        "enabled": false
+                      }
+                    },
                     "guidelines": {
                       "type": [
                         "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.102.0",
+  "version": "1.103.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/db.ts

@@ -1,8 +1,6 @@
 import { Database } from "bun:sqlite";
 import { parseProviderMeta } from "@/utils/provider-metadata.ts";
 import pkg from "../../package.json";
-import { addEyesReactionOnTaskStart } from "../github/task-reactions";
-import { type ModelTier, parseModelTier } from "../model-tiers";
 import { configureDbResolver } from "../prompts/resolver";
 import { telemetry } from "../telemetry";
 import type {
@@ -101,7 +99,12 @@ import type {
   WorkflowSummary,
   WorkflowVersion,
 } from "../types";
-import { FollowUpConfigSchema, isTerminalTaskStatus } from "../types";
+import {
+  FollowUpConfigSchema,
+  isTerminalTaskStatus,
+  type ModelTier,
+  parseModelTier,
+} from "../types";
 import { deriveProviderFromKeyType } from "../utils/credentials";
 import type { RateLimitWindowTelemetry } from "../utils/error-tracker";
 import { getCurrentRequestUserId } from "../utils/request-auth-context";
@@ -111,11 +114,17 @@ import { normalizeDate, normalizeDateRequired } from "./date-utils";
 import { runMigrations } from "./migrations/runner";
 import { seedDefaultTemplates } from "./seed-prompt-templates";
 import { isReservedConfigKey, reservedKeyError } from "./swarm-config-guard";
+import { emitTaskStarted } from "./task-lifecycle-events";
 
 let db: Database | null = null;
 let sqliteVecAvailable = false;
 
 type TaskTelemetryProps = Parameters<typeof telemetry.taskEvent>[1];
+type TaskTelemetryContext = {
+  provider?: ProviderName;
+  harnessVariant?: string;
+  harnessVersion?: string;
+};
 
 function emitTaskLifecycleTelemetryAfterCommit(
   event: string,
@@ -128,6 +137,17 @@ function emitTaskLifecycleTelemetryAfterCommit(
   });
 }
 
+function taskContextForTelemetry(task: AgentTask): TaskTelemetryContext {
+  const harnessVersion = task.harnessVariantMeta?.version;
+  const context: TaskTelemetryContext = {};
+  if (task.provider) context.provider = task.provider;
+  if (task.harnessVariant) context.harnessVariant = task.harnessVariant;
+  if (typeof harnessVersion === "string" || typeof harnessVersion === "number") {
+    context.harnessVersion = String(harnessVersion);
+  }
+  return context;
+}
+
 export function isSqliteVecAvailable(): boolean {
   return sqliteVecAvailable;
 }
@@ -1375,9 +1395,9 @@ export function startTask(taskId: string): AgentTask | null {
     } catch {}
   }
   const result = row ? rowToAgentTask(row) : null;
-  // Fire-and-forget: add eyes reaction for GitHub-sourced tasks
+  // Fire-and-forget: notify lifecycle subscribers (e.g. GitHub eyes reaction)
   if (result && oldTask.status !== "in_progress") {
-    addEyesReactionOnTaskStart(result).catch(() => {});
+    emitTaskStarted(result);
   }
   return result;
 }
@@ -2153,6 +2173,8 @@ export function completeTask(id: string, output?: string): AgentTask | null {
       "completed",
       {
         taskId: id,
+        source: oldTask.source,
+        ...taskContextForTelemetry(oldTask),
         agentId: row.agentId ?? undefined,
         durationMs: row.createdAt ? Date.now() - new Date(row.createdAt).getTime() : undefined,
       },
@@ -2203,6 +2225,8 @@ export function failTask(id: string, reason: string): AgentTask | null {
       "failed",
       {
         taskId: id,
+        source: oldTask.source,
+        ...taskContextForTelemetry(oldTask),
         agentId: row.agentId ?? undefined,
         durationMs: row.createdAt ? Date.now() - new Date(row.createdAt).getTime() : undefined,
       },
@@ -2337,6 +2361,21 @@ export function supersedeTask(
     .get(finishedAt, id);
 
   if (row && oldTask) {
+    emitTaskLifecycleTelemetryAfterCommit(
+      "superseded",
+      {
+        taskId: id,
+        source: oldTask.source,
+        ...taskContextForTelemetry(oldTask),
+        agentId: row.agentId ?? undefined,
+        reason: args.reason,
+        durationMs: oldTask.createdAt
+          ? Date.now() - new Date(oldTask.createdAt).getTime()
+          : undefined,
+      },
+      (task) => task?.status === "superseded",
+    );
+
     try {
       createLogEntry({
         eventType: "task_superseded",
@@ -3255,7 +3294,7 @@ export function createTaskExtended(task: string, options?: CreateTaskOptions): A
     {
       taskId: row.id,
       source: row.source,
-      tags: options?.tags ?? [],
+      ...taskContextForTelemetry(rowToAgentTask(row)),
       hasParent: !!row.parentTaskId,
       priority: row.priority,
     },
@@ -3305,9 +3344,9 @@ export function claimTask(taskId: string, agentId: string): AgentTask | null {
   }
 
   const result = row ? rowToAgentTask(row) : null;
-  // Fire-and-forget: add eyes reaction for GitHub-sourced tasks
+  // Fire-and-forget: notify lifecycle subscribers (e.g. GitHub eyes reaction)
   if (result) {
-    addEyesReactionOnTaskStart(result).catch(() => {});
+    emitTaskStarted(result);
   }
   return result;
 }
@@ -6183,6 +6222,7 @@ type SwarmRepoRow = {
   clonePath: string;
   defaultBranch: string;
   autoClone: number; // SQLite boolean
+  hooks: string | null;
   guidelines: string | null;
   createdAt: string;
   lastUpdatedAt: string;
@@ -6196,6 +6236,7 @@ function rowToSwarmRepo(row: SwarmRepoRow): SwarmRepo {
     clonePath: row.clonePath,
     defaultBranch: row.defaultBranch,
     autoClone: row.autoClone === 1,
+    hooks: row.hooks ? JSON.parse(row.hooks) : { enabled: false },
     guidelines: row.guidelines ? JSON.parse(row.guidelines) : null,
     createdAt: row.createdAt,
     lastUpdatedAt: row.lastUpdatedAt,
@@ -6251,20 +6292,22 @@ export function createSwarmRepo(data: {
   clonePath?: string;
   defaultBranch?: string;
   autoClone?: boolean;
+  hooks?: { enabled: boolean };
   guidelines?: RepoGuidelines | null;
 }): SwarmRepo {
   const id = crypto.randomUUID();
   const now = new Date().toISOString();
-  const clonePath = data.clonePath || `/workspace/repos/${data.name}`;
+  const clonePath = data.clonePath || `/workspace/personal/repos/${data.name}`;
+  const hooksJson = JSON.stringify(data.hooks ?? { enabled: true });
   const guidelinesJson = data.guidelines ? JSON.stringify(data.guidelines) : null;
 
   const row = getDb()
     .prepare<
       SwarmRepoRow,
-      [string, string, string, string, string, number, string | null, string, string]
+      [string, string, string, string, string, number, string | null, string | null, string, string]
     >(
-      `INSERT INTO swarm_repos (id, url, name, clonePath, defaultBranch, autoClone, guidelines, createdAt, lastUpdatedAt)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+      `INSERT INTO swarm_repos (id, url, name, clonePath, defaultBranch, autoClone, hooks, guidelines, createdAt, lastUpdatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     )
     .get(
       id,
@@ -6273,6 +6316,7 @@ export function createSwarmRepo(data: {
       clonePath,
       data.defaultBranch ?? "main",
       data.autoClone !== false ? 1 : 0,
+      hooksJson,
       guidelinesJson,
       now,
       now,
@@ -6290,6 +6334,7 @@ export function updateSwarmRepo(
     clonePath: string;
     defaultBranch: string;
     autoClone: boolean;
+    hooks: { enabled: boolean } | null;
     guidelines: RepoGuidelines | null;
   }>,
 ): SwarmRepo | null {
@@ -6307,6 +6352,10 @@ export function updateSwarmRepo(
     setClauses.push("autoClone = ?");
     params.push(updates.autoClone ? 1 : 0);
   }
+  if (updates.hooks !== undefined) {
+    setClauses.push("hooks = ?");
+    params.push(updates.hooks ? JSON.stringify(updates.hooks) : null);
+  }
   if (updates.guidelines !== undefined) {
     setClauses.push("guidelines = ?");
     params.push(updates.guidelines ? JSON.stringify(updates.guidelines) : null);
@@ -7037,6 +7086,22 @@ export function getWorkflowRun(id: string): WorkflowRun | null {
   return row ? rowToWorkflowRun(row) : null;
 }
 
+function emitWorkflowTerminalTelemetry(run: WorkflowRun): void {
+  if (run.status !== "completed" && run.status !== "failed") return;
+
+  queueMicrotask(() => {
+    const latest = getWorkflowRun(run.id);
+    if (!latest || latest.status !== run.status) return;
+    const steps = getWorkflowRunStepsByRunId(run.id);
+    telemetry.workflow(run.status, {
+      workflowId: run.workflowId,
+      durationMs: run.startedAt ? Date.now() - new Date(run.startedAt).getTime() : undefined,
+      stepsCompleted: steps.filter((step) => step.status === "completed").length,
+      stepsFailed: steps.filter((step) => step.status === "failed").length,
+    });
+  });
+}
+
 export function updateWorkflowRun(
   id: string,
   data: {
@@ -7073,7 +7138,12 @@ export function updateWorkflowRun(
       `UPDATE workflow_runs SET ${updates.join(", ")} WHERE id = ? RETURNING *`,
     )
     .get(...params);
-  return row ? rowToWorkflowRun(row) : null;
+  if (!row) return null;
+  const run = rowToWorkflowRun(row);
+  if (data.status === "completed" || data.status === "failed") {
+    emitWorkflowTerminalTelemetry(run);
+  }
+  return run;
 }
 
 export function listWorkflowRuns(workflowId: string): WorkflowRun[] {

package/src/be/migrations/098_repo_hooks_config.sql

@@ -0,0 +1,3 @@
+-- Add opt-in hook installation config for worker repo setup.
+-- Stores a JSON string of { enabled: boolean }. NULL means hooks are disabled.
+ALTER TABLE swarm_repos ADD COLUMN hooks TEXT DEFAULT NULL;

package/src/be/task-lifecycle-events.ts

@@ -0,0 +1,42 @@
+import type { AgentTask } from "../types";
+
+/**
+ * Minimal in-process task-lifecycle event emitter.
+ *
+ * This exists to invert a layering dependency: the data layer (`be/db`) used to
+ * import a GitHub integration (`github/task-reactions`) so it could add an 👀
+ * reaction when a task started. Instead, `be/db` now emits a `task-started`
+ * event and the GitHub integration subscribes at API-server boot. The data layer
+ * no longer depends on any integration.
+ *
+ * Handlers run synchronously in registration order. Each is wrapped in try/catch
+ * so a throwing handler never breaks task processing. Handlers may return a
+ * promise; it is ignored (fire-and-forget), but any async rejection is swallowed
+ * so it never surfaces as an unhandled rejection. This preserves the original
+ * `addEyesReactionOnTaskStart(result).catch(() => {})` semantics exactly.
+ */
+
+type TaskStartedHandler = (task: AgentTask) => void | Promise<void>;
+
+const taskStartedHandlers: TaskStartedHandler[] = [];
+
+/** Register a handler invoked whenever a task transitions to `in_progress`. */
+export function onTaskStarted(handler: TaskStartedHandler): void {
+  taskStartedHandlers.push(handler);
+}
+
+/** Emit the task-started event. Never throws. */
+export function emitTaskStarted(task: AgentTask): void {
+  for (const handler of taskStartedHandlers) {
+    try {
+      const result = handler(task);
+      // Fire-and-forget: ignore the returned promise but swallow async
+      // rejections so a failing handler never crashes the process.
+      if (result && typeof (result as Promise<void>).catch === "function") {
+        (result as Promise<void>).catch(() => {});
+      }
+    } catch {
+      // A throwing handler must never break task processing.
+    }
+  }
+}