vellum 0.2.1 → 0.2.7

package/src/schedule/schedule-store.ts

@@ -2,12 +2,16 @@ import { and, asc, desc, eq, lte } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { Cron } from 'croner';
 import { getDb } from '../memory/db.js';
-import { cronJobs, cronRuns } from '../memory/schema.js';
+import { scheduleJobs, scheduleRuns } from '../memory/schema.js';
+import { computeNextRunAt as computeNextRunAtEngine, isValidScheduleExpression } from './recurrence-engine.js';
+import type { ScheduleSyntax } from './recurrence-types.js';
 
 export interface ScheduleJob {
   id: string;
   name: string;
   enabled: boolean;
+  syntax: ScheduleSyntax;
+  expression: string;
   cronExpression: string;
   timezone: string | null;
   message: string;
@@ -48,7 +52,7 @@ export function computeNextRunAt(cronExpression: string, timezone?: string | nul
   });
   const next = cron.nextRun();
   if (!next) {
-    throw new Error(`Cron expression "${cronExpression}" has no upcoming runs`);
+    throw new Error(`Schedule expression "${cronExpression}" has no upcoming runs`);
   }
   return next.getTime();
 }
@@ -60,9 +64,16 @@ export function createSchedule(params: {
   message: string;
   enabled?: boolean;
   createdBy?: string;
+  syntax?: ScheduleSyntax;
+  expression?: string;
 }): ScheduleJob {
-  if (!isValidCronExpression(params.cronExpression)) {
-    throw new Error(`Invalid cron expression: "${params.cronExpression}"`);
+  // Resolve syntax and expression: prefer explicit values, fall back to cron default
+  const syntax: ScheduleSyntax = params.syntax ?? 'cron';
+  const expression = params.expression ?? params.cronExpression;
+
+  const spec = { syntax, expression, timezone: params.timezone };
+  if (!isValidScheduleExpression(spec)) {
+    throw new Error(`Invalid ${syntax} expression: "${expression}"`);
   }
 
   const db = getDb();
@@ -70,13 +81,14 @@ export function createSchedule(params: {
   const now = Date.now();
   const enabled = params.enabled ?? true;
   const timezone = params.timezone ?? null;
-  const nextRunAt = enabled ? computeNextRunAt(params.cronExpression, timezone) : 0;
+  const nextRunAt = enabled ? computeNextRunAtEngine(spec) : 0;
 
   const row = {
     id,
     name: params.name,
     enabled,
-    cronExpression: params.cronExpression,
+    cronExpression: expression,
+    scheduleSyntax: syntax,
     timezone,
     message: params.message,
     nextRunAt,
@@ -88,16 +100,16 @@ export function createSchedule(params: {
     updatedAt: now,
   };
 
-  db.insert(cronJobs).values(row).run();
-  return row;
+  db.insert(scheduleJobs).values(row).run();
+  return parseJobRow(row);
 }
 
 export function getSchedule(id: string): ScheduleJob | null {
   const db = getDb();
   const row = db
     .select()
-    .from(cronJobs)
-    .where(eq(cronJobs.id, id))
+    .from(scheduleJobs)
+    .where(eq(scheduleJobs.id, id))
     .get();
   if (!row) return null;
   return parseJobRow(row);
@@ -105,12 +117,12 @@ export function getSchedule(id: string): ScheduleJob | null {
 
 export function listSchedules(options?: { enabledOnly?: boolean }): ScheduleJob[] {
   const db = getDb();
-  const conditions = options?.enabledOnly ? eq(cronJobs.enabled, true) : undefined;
+  const conditions = options?.enabledOnly ? eq(scheduleJobs.enabled, true) : undefined;
   const rows = db
     .select()
-    .from(cronJobs)
+    .from(scheduleJobs)
     .where(conditions)
-    .orderBy(asc(cronJobs.nextRunAt))
+    .orderBy(asc(scheduleJobs.nextRunAt))
     .all();
   return rows.map(parseJobRow);
 }
@@ -123,90 +135,120 @@ export function updateSchedule(
     timezone?: string | null;
     message?: string;
     enabled?: boolean;
+    syntax?: ScheduleSyntax;
+    expression?: string;
   },
 ): ScheduleJob | null {
   const db = getDb();
-  const existing = db.select().from(cronJobs).where(eq(cronJobs.id, id)).get();
+  const existing = db.select().from(scheduleJobs).where(eq(scheduleJobs.id, id)).get();
   if (!existing) return null;
 
-  if (updates.cronExpression && !isValidCronExpression(updates.cronExpression)) {
-    throw new Error(`Invalid cron expression: "${updates.cronExpression}"`);
+  // Resolve the effective syntax and expression after this update
+  const newSyntax = updates.syntax ?? (existing.scheduleSyntax as ScheduleSyntax) ?? 'cron';
+  const newExpr = updates.expression ?? updates.cronExpression ?? existing.cronExpression;
+  const newTimezone = updates.timezone !== undefined ? updates.timezone : existing.timezone;
+  const newEnabled = updates.enabled !== undefined ? updates.enabled : existing.enabled;
+
+  // Validate if expression or syntax changed
+  if (updates.expression !== undefined || updates.cronExpression !== undefined || updates.syntax !== undefined) {
+    const spec = { syntax: newSyntax, expression: newExpr, timezone: newTimezone };
+    if (!isValidScheduleExpression(spec)) {
+      throw new Error(`Invalid ${newSyntax} expression: "${newExpr}"`);
+    }
   }
 
   const now = Date.now();
   const set: Record<string, unknown> = { updatedAt: now };
 
   if (updates.name !== undefined) set.name = updates.name;
-  if (updates.cronExpression !== undefined) set.cronExpression = updates.cronExpression;
+  if (updates.cronExpression !== undefined || updates.expression !== undefined) set.cronExpression = newExpr;
+  if (updates.syntax !== undefined) set.scheduleSyntax = newSyntax;
   if (updates.timezone !== undefined) set.timezone = updates.timezone;
   if (updates.message !== undefined) set.message = updates.message;
   if (updates.enabled !== undefined) set.enabled = updates.enabled;
 
-  const newExpr = updates.cronExpression ?? existing.cronExpression;
-  const newTimezone = updates.timezone !== undefined ? updates.timezone : existing.timezone;
-  const newEnabled = updates.enabled !== undefined ? updates.enabled : existing.enabled;
-
+  // Recompute nextRunAt if schedule timing may have changed
   if (
     updates.cronExpression !== undefined ||
+    updates.expression !== undefined ||
+    updates.syntax !== undefined ||
     updates.timezone !== undefined ||
     updates.enabled !== undefined
   ) {
-    set.nextRunAt = newEnabled ? computeNextRunAt(newExpr, newTimezone) : 0;
+    const spec = { syntax: newSyntax, expression: newExpr, timezone: newTimezone };
+    set.nextRunAt = newEnabled ? computeNextRunAtEngine(spec) : 0;
   }
 
-  db.update(cronJobs).set(set).where(eq(cronJobs.id, id)).run();
+  db.update(scheduleJobs).set(set).where(eq(scheduleJobs.id, id)).run();
 
   return getSchedule(id);
 }
 
 export function deleteSchedule(id: string): boolean {
   const db = getDb();
-  const result = db.delete(cronJobs).where(eq(cronJobs.id, id)).run() as unknown as { changes?: number };
+  const result = db.delete(scheduleJobs).where(eq(scheduleJobs.id, id)).run() as unknown as { changes?: number };
   return (result.changes ?? 0) > 0;
 }
 
 /**
- * Claim due schedules atomically. For each candidate where enabled=true and
- * next_run_at <= now, we advance next_run_at using optimistic locking on the
- * old value to prevent double-claiming by concurrent ticks.
+ * Claim due recurrence schedules atomically. For each candidate where
+ * enabled=true and next_run_at <= now, we advance next_run_at using
+ * optimistic locking on the old value to prevent double-claiming by
+ * concurrent ticks. Works for both cron and RRULE syntax.
  */
 export function claimDueSchedules(now: number): ScheduleJob[] {
   const db = getDb();
   const candidates = db
     .select()
-    .from(cronJobs)
-    .where(and(eq(cronJobs.enabled, true), lte(cronJobs.nextRunAt, now)))
-    .orderBy(asc(cronJobs.nextRunAt))
+    .from(scheduleJobs)
+    .where(and(eq(scheduleJobs.enabled, true), lte(scheduleJobs.nextRunAt, now)))
+    .orderBy(asc(scheduleJobs.nextRunAt))
     .all();
 
   const claimed: ScheduleJob[] = [];
   for (const row of candidates) {
-    let newNextRunAt: number;
+    let newNextRunAt: number | null;
+    let exhausted = false;
     try {
-      newNextRunAt = computeNextRunAt(row.cronExpression, row.timezone);
+      const syntax = (row.scheduleSyntax as ScheduleSyntax) ?? 'cron';
+      newNextRunAt = computeNextRunAtEngine({
+        syntax,
+        expression: row.cronExpression,
+        timezone: row.timezone,
+      });
     } catch {
-      // Expression has no future runs — skip
-      continue;
+      // Finite schedule with no future runs — still claim the current due
+      // run but disable the schedule so it doesn't fire again.
+      newNextRunAt = null;
+      exhausted = true;
     }
 
     // Optimistic lock: only update if nextRunAt hasn't changed
+    const updates: Record<string, unknown> = {
+      lastRunAt: now,
+      updatedAt: now,
+    };
+    if (exhausted) {
+      updates.nextRunAt = 0;
+      updates.enabled = false;
+    } else {
+      updates.nextRunAt = newNextRunAt!;
+    }
+
     const result = db
-      .update(cronJobs)
-      .set({
-        nextRunAt: newNextRunAt,
-        lastRunAt: now,
-        updatedAt: now,
-      })
-      .where(and(eq(cronJobs.id, row.id), eq(cronJobs.nextRunAt, row.nextRunAt)))
+      .update(scheduleJobs)
+      .set(updates)
+      .where(and(eq(scheduleJobs.id, row.id), eq(scheduleJobs.nextRunAt, row.nextRunAt)))
       .run() as unknown as { changes?: number };
 
     if ((result.changes ?? 0) === 0) continue;
 
     claimed.push(parseJobRow({
       ...row,
-      nextRunAt: newNextRunAt,
+      nextRunAt: exhausted ? 0 : newNextRunAt!,
       lastRunAt: now,
       updatedAt: now,
+      enabled: exhausted ? false : row.enabled,
     }));
   }
   return claimed;
@@ -216,7 +258,7 @@ export function createScheduleRun(jobId: string, conversationId: string): string
   const db = getDb();
   const id = uuid();
   const now = Date.now();
-  db.insert(cronRuns).values({
+  db.insert(scheduleRuns).values({
     id,
     jobId,
     status: 'running',
@@ -238,12 +280,12 @@ export function completeScheduleRun(
   const db = getDb();
   const now = Date.now();
 
-  const run = db.select().from(cronRuns).where(eq(cronRuns.id, runId)).get();
+  const run = db.select().from(scheduleRuns).where(eq(scheduleRuns.id, runId)).get();
   if (!run) return;
 
   const durationMs = now - run.startedAt;
 
-  db.update(cronRuns)
+  db.update(scheduleRuns)
     .set({
       status: result.status,
       finishedAt: now,
@@ -251,23 +293,23 @@ export function completeScheduleRun(
       output: result.output?.slice(0, 10_000) ?? null,
       error: result.error?.slice(0, 2000) ?? null,
     })
-    .where(eq(cronRuns.id, runId))
+    .where(eq(scheduleRuns.id, runId))
     .run();
 
   // Update the parent job's lastStatus and retryCount
   if (result.status === 'error') {
     // Increment retry count
-    const job = db.select().from(cronJobs).where(eq(cronJobs.id, run.jobId)).get();
+    const job = db.select().from(scheduleJobs).where(eq(scheduleJobs.id, run.jobId)).get();
     if (job) {
-      db.update(cronJobs)
+      db.update(scheduleJobs)
         .set({ lastStatus: 'error', retryCount: job.retryCount + 1, updatedAt: now })
-        .where(eq(cronJobs.id, run.jobId))
+        .where(eq(scheduleJobs.id, run.jobId))
         .run();
     }
   } else {
-    db.update(cronJobs)
+    db.update(scheduleJobs)
       .set({ lastStatus: 'ok', retryCount: 0, updatedAt: now })
-      .where(eq(cronJobs.id, run.jobId))
+      .where(eq(scheduleJobs.id, run.jobId))
       .run();
   }
 }
@@ -276,9 +318,9 @@ export function getScheduleRuns(jobId: string, limit?: number): ScheduleRun[] {
   const db = getDb();
   const rows = db
     .select()
-    .from(cronRuns)
-    .where(eq(cronRuns.jobId, jobId))
-    .orderBy(desc(cronRuns.createdAt))
+    .from(scheduleRuns)
+    .where(eq(scheduleRuns.jobId, jobId))
+    .orderBy(desc(scheduleRuns.createdAt))
     .limit(limit ?? 10)
     .all();
   return rows.map(parseRunRow);
@@ -296,7 +338,8 @@ export function formatLocalDate(timestamp: number): string {
 }
 
 // Convert a cron expression to a human-readable description.
-// Uses the croner library to parse the expression and inspect its pattern fields.
+// Only applicable to cron syntax; RRULE schedules should display the
+// raw expression text instead.
 //
 // Examples:
 //   "* * * * *"     -> "Every minute"
@@ -418,11 +461,13 @@ export function describeCronExpression(expr: string): string {
   }
 }
 
-function parseJobRow(row: typeof cronJobs.$inferSelect): ScheduleJob {
+function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
   return {
     id: row.id,
     name: row.name,
     enabled: row.enabled,
+    syntax: (row.scheduleSyntax as ScheduleSyntax) ?? 'cron',
+    expression: row.cronExpression,
     cronExpression: row.cronExpression,
     timezone: row.timezone,
     message: row.message,
@@ -436,7 +481,7 @@ function parseJobRow(row: typeof cronJobs.$inferSelect): ScheduleJob {
   };
 }
 
-function parseRunRow(row: typeof cronRuns.$inferSelect): ScheduleRun {
+function parseRunRow(row: typeof scheduleRuns.$inferSelect): ScheduleRun {
   return {
     id: row.id,
     jobId: row.jobId,

package/src/schedule/scheduler.ts

@@ -5,6 +5,7 @@ import {
   createScheduleRun,
   completeScheduleRun,
 } from './schedule-store.js';
+import { hasSetConstructs } from './recurrence-engine.js';
 import { claimDueReminders, completeReminder, failReminder, setReminderConversationId } from '../tools/reminder/reminder-store.js';
 import { runWatchersOnce, type WatcherNotifier, type WatcherEscalator } from '../watcher/engine.js';
 
@@ -73,19 +74,20 @@ async function runScheduleOnce(
   const now = Date.now();
   let processed = 0;
 
-  // ── Cron jobs ───────────────────────────────────────────────────────
+  // ── Recurrence schedules (cron + RRULE) ─────────────────────────────
   const jobs = claimDueSchedules(now);
   for (const job of jobs) {
     // Check if message is a task invocation (run_task:<task_id>)
     const taskMatch = job.message.match(/^run_task:(\S+)$/);
     if (taskMatch) {
       const taskId = taskMatch[1];
+      const isRruleSet = job.syntax === 'rrule' && hasSetConstructs(job.expression);
       try {
-        log.info({ jobId: job.id, name: job.name, taskId }, 'Executing scheduled task');
+        log.info({ jobId: job.id, name: job.name, taskId, syntax: job.syntax, expression: job.expression, isRruleSet }, 'Executing scheduled task');
         const { runTask } = await import('../tasks/task-runner.js');
         const result = await runTask(
           { taskId, workingDir: process.cwd() },
-          processMessage as (conversationId: string, message: string) => Promise<void>,
+          processMessage as (conversationId: string, message: string, taskRunId: string) => Promise<void>,
         );
 
         // Track the schedule run using the task's conversation
@@ -99,7 +101,7 @@ async function runScheduleOnce(
         processed += 1;
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        log.warn({ err, jobId: job.id, name: job.name, taskId }, 'Scheduled task execution failed');
+        log.warn({ err, jobId: job.id, name: job.name, taskId, syntax: job.syntax, expression: job.expression, isRruleSet }, 'Scheduled task execution failed');
         // Create a fallback conversation for the schedule run record
         const fallbackConversation = createConversation(`Schedule: ${job.name}`);
         const runId = createScheduleRun(job.id, fallbackConversation.id);
@@ -110,16 +112,17 @@ async function runScheduleOnce(
 
     const conversation = createConversation(`Schedule: ${job.name}`);
     const runId = createScheduleRun(job.id, conversation.id);
+    const isRruleSetMsg = job.syntax === 'rrule' && hasSetConstructs(job.expression);
 
     try {
-      log.info({ jobId: job.id, name: job.name, conversationId: conversation.id }, 'Executing schedule');
+      log.info({ jobId: job.id, name: job.name, syntax: job.syntax, expression: job.expression, isRruleSet: isRruleSetMsg, conversationId: conversation.id }, 'Executing schedule');
       await processMessage(conversation.id, job.message);
       completeScheduleRun(runId, { status: 'ok' });
       notifySchedule({ id: job.id, name: job.name });
       processed += 1;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      log.warn({ err, jobId: job.id, name: job.name }, 'Schedule execution failed');
+      log.warn({ err, jobId: job.id, name: job.name, syntax: job.syntax, expression: job.expression, isRruleSet: isRruleSetMsg }, 'Schedule execution failed');
       completeScheduleRun(runId, { status: 'error', error: message });
     }
   }

package/src/security/oauth2.ts

@@ -6,6 +6,9 @@
  */
 
 import { randomBytes, createHash } from 'node:crypto';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('oauth2');
 
 // ---------------------------------------------------------------------------
 // Types
@@ -170,8 +173,19 @@ export async function startOAuth2Flow(
     });
 
     if (!tokenResp.ok) {
-      const body = await tokenResp.text().catch(() => '');
-      throw new Error(`OAuth2 token exchange failed (${tokenResp.status}): ${body}`);
+      const rawBody = await tokenResp.text().catch(() => '');
+      let safeDetail: Record<string, unknown> = {};
+      let errorCode = '';
+      try {
+        const parsed = JSON.parse(rawBody) as Record<string, unknown>;
+        if (parsed.error) { safeDetail.error = String(parsed.error); errorCode = String(parsed.error); }
+        if (parsed.error_description) safeDetail.error_description = String(parsed.error_description);
+      } catch {
+        safeDetail.error = '[non-JSON response]';
+      }
+      log.error({ status: tokenResp.status, ...safeDetail }, 'OAuth2 token exchange failed');
+      const detail = errorCode ? `HTTP ${tokenResp.status}: ${errorCode}` : `HTTP ${tokenResp.status}`;
+      throw new Error(`OAuth2 token exchange failed (${detail})`);
     }
 
     const tokenData = await tokenResp.json() as Record<string, unknown>;
@@ -225,8 +239,19 @@ export async function refreshOAuth2Token(
   });
 
   if (!resp.ok) {
-    const body = await resp.text().catch(() => '');
-    throw new Error(`OAuth2 token refresh failed (${resp.status}): ${body}`);
+    const rawBody = await resp.text().catch(() => '');
+    let safeDetail: Record<string, unknown> = {};
+    let errorCode = '';
+    try {
+      const parsed = JSON.parse(rawBody) as Record<string, unknown>;
+      if (parsed.error) { safeDetail.error = String(parsed.error); errorCode = String(parsed.error); }
+      if (parsed.error_description) safeDetail.error_description = String(parsed.error_description);
+    } catch {
+      safeDetail.error = '[non-JSON response]';
+    }
+    log.error({ status: resp.status, ...safeDetail }, 'OAuth2 token refresh failed');
+    const detail = errorCode ? `HTTP ${resp.status}: ${errorCode}` : `HTTP ${resp.status}`;
+    throw new Error(`OAuth2 token refresh failed (${detail})`);
   }
 
   const data = await resp.json() as Record<string, unknown>;

package/src/security/secret-allowlist.ts

@@ -104,6 +104,52 @@ export function isAllowlisted(value: string): boolean {
   return false;
 }
 
+export interface AllowlistValidationError {
+  index: number;
+  pattern: string;
+  message: string;
+}
+
+/**
+ * Validate all regex patterns in an allowlist config without loading them.
+ * Returns an array of validation errors (empty = all valid).
+ */
+export function validateAllowlist(config: AllowlistConfig): AllowlistValidationError[] {
+  const errors: AllowlistValidationError[] = [];
+  if (!config.patterns) return errors;
+  if (!Array.isArray(config.patterns)) {
+    errors.push({ index: -1, pattern: String(config.patterns), message: '"patterns" must be an array' });
+    return errors;
+  }
+
+  for (let i = 0; i < config.patterns.length; i++) {
+    const p = config.patterns[i];
+    if (typeof p !== 'string') {
+      errors.push({ index: i, pattern: String(p), message: 'Pattern is not a string' });
+      continue;
+    }
+    try {
+      new RegExp(p);
+    } catch (err) {
+      errors.push({ index: i, pattern: p, message: (err as Error).message });
+    }
+  }
+  return errors;
+}
+
+/**
+ * Read secret-allowlist.json from disk and validate it.
+ * Returns validation errors, or null if the file doesn't exist.
+ */
+export function validateAllowlistFile(): AllowlistValidationError[] | null {
+  const filePath = join(getRootDir(), 'protected', 'secret-allowlist.json');
+  if (!existsSync(filePath)) return null;
+
+  const raw = readFileSync(filePath, 'utf-8');
+  const config: AllowlistConfig = JSON.parse(raw);
+  return validateAllowlist(config);
+}
+
 /**
  * Reset cached state so the allowlist is reloaded on next check.
  * Called by the daemon file watcher when secret-allowlist.json changes,

package/src/skills/clawhub.ts

@@ -395,7 +395,7 @@ export async function clawhubInspect(slug: string): Promise<{ data?: ClawhubInsp
           size: (f.size as number) ?? 0,
           contentType: (f.contentType as string) ?? undefined,
         })) : null,
-        skillMdContent: parsed.skillMdContent ?? parsed.fileContents?.['SKILL.md'] ?? null,
+        skillMdContent: parsed.skillMdContent ?? parsed.fileContents?.['SKILL.md'] ?? parsed.file?.content ?? null,
       };
       return { data };
     } catch {

package/src/subagent/manager.ts

@@ -52,10 +52,18 @@ interface ManagedSubagent {
   parentSendToClient: (msg: ServerMessage) => void;
 }
 
+export interface SubagentNotificationInfo {
+  subagentId: string;
+  label: string;
+  status: 'completed' | 'failed' | 'aborted';
+  error?: string;
+}
+
 export type ParentNotifyCallback = (
   parentSessionId: string,
   message: string,
   sendToClient: (msg: ServerMessage) => void,
+  notification: SubagentNotificationInfo,
 ) => void;
 
 export class SubagentManager {
@@ -221,6 +229,8 @@ export class SubagentManager {
       await managed.session.runAgentLoop(objective, messageId, onEvent);
 
       // Agent loop completed successfully.
+      // Copy usage stats from the session before sending status (which includes usage).
+      managed.state.usage = { ...managed.session.usageStats };
       // Only update state + notify if still non-terminal (guards against abort race).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
         managed.state.completedAt = Date.now();
@@ -235,6 +245,7 @@ export class SubagentManager {
       const errorMsg = err instanceof Error ? err.message : String(err);
       managed.state.error = errorMsg;
       managed.state.completedAt = Date.now();
+      managed.state.usage = { ...managed.session.usageStats };
 
       // Only update status if not already terminal (e.g. aborted).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
@@ -267,16 +278,28 @@ export class SubagentManager {
     managed.session.abort();
     managed.state.completedAt = Date.now();
     if (parentSendToClient) {
-      this.setStatus(subagentId, 'aborted', parentSendToClient);
-      // Notify parent about the abort — skip when the parent already has the
-      // tool result (e.g. subagent_abort tool) to avoid duplicate turns.
+      // Route the status update through the stored parent sender so the
+      // owning session's UI chip updates, even when the abort comes from a
+      // different socket (e.g. after thread switching). Fall back to the
+      // caller-provided sender if no stored sender exists.
+      const statusSender = managed.parentSendToClient ?? parentSendToClient;
+      this.setStatus(subagentId, 'aborted', statusSender);
+      // Notify parent that the subagent was explicitly aborted — tell it NOT to re-spawn.
+      // Skip when the parent LLM itself called subagent_abort (it already has the tool result).
       if (this.onSubagentFinished && !options?.suppressNotification) {
         const label = managed.state.config.label;
+        const message =
+          `[Subagent "${label}" was explicitly aborted]\n\n` +
+          `This subagent was cancelled on purpose. Do NOT re-spawn or retry it.`;
         try {
+          // Use the managed subagent's stored parentSendToClient so the
+          // notification routes to the parent session's socket, not the
+          // aborting socket (which may be a different thread after switching).
           this.onSubagentFinished(
             managed.state.config.parentSessionId,
-            `[Subagent "${label}" was aborted]`,
-            parentSendToClient,
+            message,
+            managed.parentSendToClient,
+            { subagentId, label, status: 'aborted' },
           );
         } catch (err) {
           log.error({ subagentId, err }, 'Failed to notify parent about abort');
@@ -460,16 +483,25 @@ export class SubagentManager {
     if (outcome === 'completed') {
       message =
         `[Subagent "${config.label}" completed]\n\n` +
-        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.`;
+        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
+        `Do NOT re-spawn this subagent — just read and share the results.`;
     } else {
       const error = managed.state.error ?? 'Unknown error';
       message =
         `[Subagent "${config.label}" failed]\n\n` +
-        `Error: ${error}`;
+        `Error: ${error}\n` +
+        `Do NOT re-spawn or retry this subagent unless the user explicitly asks.`;
     }
 
+    const notification: SubagentNotificationInfo = {
+      subagentId: config.id,
+      label: config.label,
+      status: outcome,
+      ...(outcome === 'failed' ? { error: managed.state.error ?? 'Unknown error' } : {}),
+    };
+
     try {
-      this.onSubagentFinished(config.parentSessionId, message, parentSendToClient);
+      this.onSubagentFinished(config.parentSessionId, message, parentSendToClient, notification);
     } catch (err) {
       log.error({ subagentId: config.id, err }, 'Failed to notify parent session');
     }