@sema-agent/core 2.0.1 → 2.2.0

package/dist/agents/observer.d.ts

@@ -68,6 +68,15 @@ export declare class ObserverDigestTap {
     finish(reason: string): void;
 }
 export type ObserverPairingState = "armed" | "denied" | "stopped" | "retired" | "blocked";
+export declare const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export declare const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export declare class ObserverStoppedByUserError extends Error {
+    constructor(message: string);
+}
+export declare class ObserverResumeStateError extends Error {
+    constructor(message: string);
+}
+export declare const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export interface ObserverSpawner {
     spawnFirstRun(args: {
         framingPrompt: string;
@@ -76,6 +85,10 @@ export interface ObserverSpawner {
     deliver(args: {
         digest: string;
     }): Promise<void>;
+    restartFresh?(args: {
+        framingPrompt: string;
+        digest: string;
+    }): Promise<void>;
 }
 export declare class ObserverPairing {
     state: ObserverPairingState;
@@ -102,6 +115,7 @@ export declare class ObserverPairing {
     private safeOnError;
     drain(): Promise<void>;
     private pump;
+    private deliverBatch;
     retire(state: Exclude<ObserverPairingState, "armed">): void;
 }
 export declare function markObserverTaskId(taskId: string): void;

package/dist/agents/observer.js

@@ -157,10 +157,15 @@ export class ObserverDigestTap {
                     this.flushText();
                     this.pending.push({ type: "tool_result", content: truncateDigestPayload(digestTextOf(e.output)) });
                     return;
-                case "steering_injected":
+                case "steering_injected": {
                     this.flushText();
-                    this.pending.push({ type: "user_message", text: e.message ?? "(steering)" });
+                    const injected = e.preview.trim();
+                    this.pending.push({
+                        type: "user_message",
+                        text: injected ? `[injected: ${e.source}]\n${injected}` : `[injected: ${e.source}] (empty preview)`,
+                    });
                     return;
+                }
                 case "turn_end":
                     this.flushSegment();
                     return;
@@ -204,6 +209,24 @@ export class ObserverDigestTap {
         this.safeFlush(slice);
     }
 }
+export const OBSERVER_STOPPED_BY_USER_ERROR_NAME = "AgentStoppedByUserError";
+export const OBSERVER_RESUME_STATE_ERROR_NAME = "ResumeAgentStateError";
+export class ObserverStoppedByUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_STOPPED_BY_USER_ERROR_NAME;
+    }
+}
+export class ObserverResumeStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = OBSERVER_RESUME_STATE_ERROR_NAME;
+    }
+}
+function errorName(err) {
+    return err instanceof Error ? err.name : undefined;
+}
+export const OBSERVER_FRESH_START_NOTE = "[Note: your previous observation context was lost; this is a fresh start mid-task.]";
 export class ObserverPairing {
     state = "armed";
     observedEnvelopeName;
@@ -273,18 +296,22 @@ export class ObserverPairing {
                 const batch = this.buffer.splice(0, this.buffer.length);
                 try {
                     const digest = renderObserverDigestBatch(this, batch);
-                    if (!this.firstRunDone) {
-                        await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
-                        this.firstRunDone = true;
-                    }
-                    else {
-                        await this.spawner.deliver({ digest });
-                    }
+                    await this.deliverBatch(digest);
                 }
                 catch (err) {
-                    this.state = "stopped";
-                    this.buffer = [];
+                    if (errorName(err) === OBSERVER_STOPPED_BY_USER_ERROR_NAME) {
+                        this.state = "stopped";
+                        this.buffer = [];
+                        this.safeOnError(err);
+                        return;
+                    }
                     this.safeOnError(err);
+                    if (this.buffer.length > 0) {
+                        const strandedCount = this.buffer.length;
+                        this.buffer = [];
+                        this.safeOnError(new Error(`observer delivery: ${strandedCount} segment(s) enqueued mid-fault were stranded and dropped (never attempted) after: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                    return;
                 }
             }
         }
@@ -292,6 +319,33 @@ export class ObserverPairing {
             this.delivering = false;
         }
     }
+    async deliverBatch(digest) {
+        if (!this.firstRunDone) {
+            await this.spawner.spawnFirstRun({ framingPrompt: this.framingPrompt, digest });
+            this.firstRunDone = true;
+            return;
+        }
+        try {
+            await this.spawner.deliver({ digest });
+        }
+        catch (err) {
+            if (errorName(err) !== OBSERVER_RESUME_STATE_ERROR_NAME)
+                throw err;
+            const restart = this.spawner.restartFresh?.bind(this.spawner);
+            if (restart === undefined)
+                throw err;
+            try {
+                await restart({ framingPrompt: `${this.framingPrompt}\n\n${OBSERVER_FRESH_START_NOTE}`, digest });
+                this.firstRunDone = true;
+            }
+            catch (restartErr) {
+                this.firstRunDone = false;
+                throw restartErr instanceof Error
+                    ? new Error(`${restartErr.message} (after resume-state loss: ${err instanceof Error ? err.message : String(err)})`, { cause: restartErr })
+                    : restartErr;
+            }
+        }
+    }
     retire(state) {
         if (this.state !== "armed")
             return;
@@ -326,7 +380,7 @@ export function createObserverReportToolSpec(opts) {
         name: OBSERVER_REPORT_TOOL_NAME,
         contract: { contractId: "core.observer_report@1", implementationRevision: "1" },
         description: OBSERVER_REPORT_DESCRIPTION,
-        effect: "idempotent",
+        effect: "write",
         parameters: Type.Object({
             report: Type.String({
                 minLength: 1,

package/dist/agents/send-message-tool.js

@@ -2,13 +2,34 @@ import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
 import { canAccessAgentRecord } from "../core/background-agent-store.js";
-import { isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
+import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
+const TEAMMATE_MESSAGE_TAG = "teammate-message";
+function frameTeammateMessage(args) {
+    const summaryAttr = args.summary !== undefined ? ` summary="${escapeAttributeValue(args.summary)}"` : "";
+    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, args.text);
+    return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
+}
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
+const sendMessageTargetLanes = new Map();
+function withTargetLane(key, fn) {
+    const prev = sendMessageTargetLanes.get(key) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    const tail = run.then(() => undefined, () => undefined);
+    sendMessageTargetLanes.set(key, tail);
+    void tail.then(() => {
+        if (sendMessageTargetLanes.get(key) === tail)
+            sendMessageTargetLanes.delete(key);
+    });
+    return run;
+}
+function targetLaneKey(scope, targetId) {
+    return JSON.stringify([scope ?? "", targetId]);
+}
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
     return defineTool({
@@ -16,6 +37,7 @@ export function createSendMessageTool(opts) {
         contract: { contractId: "core.send_message@1", implementationRevision: "1" },
         executionMode: "parallel",
         description: `Send a follow-up message to a previously spawned background agent. ` +
+            `Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages addressed to you are delivered automatically; you don't check an inbox. ` +
             `'to' is the agent's name (set at spawn via Agent({name})) or its task_id (a…). A RUNNING agent receives the ` +
             `message at its next turn (queued — never interrupts its current work); a FINISHED agent resumes as a new ` +
             `background run with its full prior conversation preserved, so don't re-explain what it already knows. Names ` +
@@ -29,7 +51,7 @@ export function createSendMessageTool(opts) {
         parameters: Type.Object({
             to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
             message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
-            summary: Type.Optional(Type.String({ maxLength: 200, description: "A short (3-5 word) description of the follow-up." })),
+            summary: Type.Optional(Type.String({ maxLength: 200, description: "A 5-10 word summary shown as a preview in the UI (required when message is a string)" })),
         }),
         execute: async (args, ctx) => {
             const a = args;
@@ -39,6 +61,28 @@ export function createSendMessageTool(opts) {
                 return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
             if (!message)
                 return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
+            if (to === "*") {
+                return {
+                    content: 'Message not sent: broadcast (to: "*") is no longer supported — send a message per recipient.',
+                    details: { error: "broadcast_unsupported", to },
+                    isError: true,
+                };
+            }
+            if (to.includes("@")) {
+                return {
+                    content: "Message not sent: to must be a bare teammate name — there is only one team per session.",
+                    details: { error: "qualified_name_unsupported", to },
+                    isError: true,
+                };
+            }
+            const summaryArg = typeof a.summary === "string" ? a.summary.trim() : "";
+            if (summaryArg === "") {
+                return {
+                    content: "Message not sent: summary is required when message is a string — pass a 5-10 word summary of the follow-up.",
+                    details: { error: "summary_required", to },
+                    isError: true,
+                };
+            }
             const senderId = ctx.taskId ?? opts.owner;
             if (senderId !== undefined && isObserverTaskId(senderId)) {
                 return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
@@ -68,6 +112,17 @@ export function createSendMessageTool(opts) {
                         details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
                     };
                 }
+                const hasParent = ctx.parentTaskId !== undefined ||
+                    opts.uplink !== undefined ||
+                    opts.senderName !== undefined ||
+                    opts.siblingRetain !== undefined;
+                if (!hasParent) {
+                    return {
+                        content: `You are the main conversation — "main" addresses you. Send to a named agent instead.`,
+                        details: { error: "main_is_self", to },
+                        isError: true,
+                    };
+                }
                 return {
                     content: `Message not sent: "main" (the spawning conversation) is not a deliverable target here. ` +
                         `Your completion is reported to it automatically — finish your task and your final report will be relayed.`,
@@ -105,10 +160,10 @@ export function createSendMessageTool(opts) {
                 if (row.name === undefined || row.agentType === "fork")
                     return undefined;
                 const whoT3 = handle === to ? `agent ${handle}` : `agent "${to}" (${handle})`;
-                if (row.status === "killed") {
+                if (row.status === "killed" && row.stoppedBy === "user") {
                     return {
-                        content: `Message not sent: ${whoT3} was stopped${row.stoppedBy !== undefined ? ` (by ${row.stoppedBy})` : ""} — a stopped agent is not revived. Launch a new agent with the needed context instead.`,
-                        details: { error: "killed", to, ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}) },
+                        content: `Message not sent: ${whoT3} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: row.stoppedBy },
                         isError: true,
                     };
                 }
@@ -244,7 +299,9 @@ export function createSendMessageTool(opts) {
                             details: { error: "mailbox_leased", to },
                         };
                     }
-                    const revivePrompt = lease.messages.map((m) => `<teammate-message teammate_id="${m.from ?? "main"}">\n${m.content}\n</teammate-message>`).join("\n");
+                    const revivePrompt = lease.messages
+                        .map((m) => frameTeammateMessage({ from: m.from ?? "main", text: m.content }))
+                        .join("\n");
                     let spawned;
                     try {
                         spawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: revivePrompt });
@@ -354,48 +411,55 @@ export function createSendMessageTool(opts) {
                 return { content: `Message not sent: ${targetId} is a ${row.type} task, not a background agent.`, details: { error: "wrong_type", to }, isError: true };
             }
             if (row.status === "running" || row.status === "pending") {
-                const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
-                const fromLabel = opts.senderName ?? senderId ?? "main";
-                const teammateXml = `<teammate-message teammate_id="${fromLabel}"${s2Summary !== undefined ? ` summary=${JSON.stringify(s2Summary)}` : ""}>\n${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]` : message}\n</teammate-message>`;
-                const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
-                    task_id: senderId ?? "main",
-                    task_type: "background_agent",
-                    status: "event",
-                    summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
-                    result: teammateXml,
-                    seq: ++uplinkSeqGlobal,
-                }, { priority: "next" });
-                if (delivered.ok) {
-                    const receiptText = delivered.disposition === "parked"
-                        ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
-                        : delivered.disposition === "pending"
-                            ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
-                            : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
-                    return {
-                        content: receiptText,
-                        details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, ...(s2Summary !== undefined ? { summary: s2Summary } : {}) },
-                    };
-                }
-                if (delivered.reason === "no_channel") {
+                return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                    const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                    const fromLabel = opts.senderName ?? senderId ?? "main";
+                    const s2Clipped = message.length > UPLINK_RESULT_MAX
+                        ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]`
+                        : message;
+                    const teammateXml = frameTeammateMessage({ from: fromLabel, ...(s2Summary !== undefined ? { summary: s2Summary } : {}), text: s2Clipped });
+                    const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
+                        task_id: senderId ?? "main",
+                        task_type: "background_agent",
+                        status: "event",
+                        summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
+                        result: teammateXml,
+                        seq: ++uplinkSeqGlobal,
+                    }, { priority: "next" });
+                    if (delivered.ok) {
+                        const receiptText = delivered.disposition === "parked"
+                            ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
+                            : delivered.disposition === "pending"
+                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
+                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
+                        return {
+                            content: receiptText,
+                            details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, ...(s2Summary !== undefined ? { summary: s2Summary } : {}) },
+                        };
+                    }
+                    if (delivered.reason === "no_channel") {
+                        return {
+                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
+                            details: { error: "still_running", to },
+                            isError: true,
+                        };
+                    }
                     return {
-                        content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
-                        details: { error: "still_running", to },
+                        content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
+                        details: { error: "settle_race", to },
                         isError: true,
                     };
-                }
-                return {
-                    content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
-                    details: { error: "settle_race", to },
-                    isError: true,
-                };
+                });
             }
             if (row.status === "killed") {
                 const by = opts.registry.getStopAttribution(targetId);
-                return {
-                    content: `Message not sent: ${who} was stopped${by ? ` (by ${by})` : ""} — a stopped agent is not resumable. Launch a new agent with the needed context instead.`,
-                    details: { error: "killed", to, ...(by !== undefined ? { stoppedBy: by } : {}) },
-                    isError: true,
-                };
+                if (by === "user") {
+                    return {
+                        content: `Message not sent: ${who} was stopped by the user and was not resumed. Treat its work as cancelled; only start a new agent for it if the user explicitly asks.`,
+                        details: { error: "killed", to, stoppedBy: by },
+                        isError: true,
+                    };
+                }
             }
             const runLedger = ctx.subagentRetain ?? opts.retain;
             const smLedgerSessionId = ctx.sessionId ?? opts.sessionId;
@@ -409,61 +473,73 @@ export function createSendMessageTool(opts) {
                     return revived;
             }
             const ledger = (knows(sessionLedger) ? sessionLedger : undefined) ?? (knows(runLedger) ? runLedger : undefined) ?? (knows(siblingLedger) ? siblingLedger : undefined) ?? runLedger ?? sessionLedger ?? siblingLedger;
-            if (!ledger || row.toolUseId === undefined) {
+            const resumeToolUseId = row.toolUseId;
+            if (!ledger || resumeToolUseId === undefined) {
                 return {
                     content: `Message not sent: ${who}'s session was not retained (this run did not enable retainSubagentSessions), so it cannot be continued — relaunch a new agent with the needed context instead.`,
                     details: { error: "not_retained", to },
                     isError: true,
                 };
             }
-            const resume = createSubagentResume({
-                ledger,
-                parentToolCallId: row.toolUseId,
-                runner: opts.runner,
-                ...(opts.notify ? { notify: opts.notify } : {}),
-                ...(opts.sink ? { sink: opts.sink } : {}),
-                registry: opts.registry,
-                taskId: targetId,
-                taskAccess: resolvedAccess,
-                ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
-                sessionScoped: row.sessionScoped === true,
-                ...(row.description !== undefined ? { rowDescription: row.description } : {}),
-                ...(row.name !== undefined ? { rowName: row.name } : {}),
-                ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
-                ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
-                ...(row.scope !== undefined ? { rowScope: row.scope } : {}),
-                ...(row.parentTaskId !== undefined ? { rowParentTaskId: row.parentTaskId } : {}),
-                ...(row.parentSessionId !== undefined ? { rowParentSessionId: row.parentSessionId } : {}),
-                ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
-                ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
-            });
-            const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
-            const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
-            try {
-                const marker = await resume(`${fromPrefix}${summary ? `[${summary}] ${message}` : message}`);
+            if (ledger.get(resumeToolUseId)?.running === true) {
                 return {
-                    content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
-                        `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
-                    details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, ...(summary !== undefined ? { summary } : {}) },
+                    content: `Message not sent: ${who} (or a prior follow-up to it) is still running — wait for its completion notification.`,
+                    details: { error: "steering.still_running", to },
+                    isError: true,
                 };
             }
-            catch (e) {
-                const code = e?.code;
-                const text = code === "resume.retain_off"
-                    ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
-                    : code === "resume.evicted"
-                        ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
-                        : code === "resume.session_not_found"
-                            ? `${who}'s session no longer exists — relaunch a new agent instead.`
-                            : code === "resume.cap"
-                                ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
-                                : code === "steering.still_running"
-                                    ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
-                                    : code === "resume.row_gone"
-                                        ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
-                                        : `${e instanceof Error ? e.message : String(e)}`;
-                return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
-            }
+            return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
+                const resume = createSubagentResume({
+                    ledger,
+                    parentToolCallId: resumeToolUseId,
+                    runner: opts.runner,
+                    ...(opts.notify ? { notify: opts.notify } : {}),
+                    ...(opts.sink ? { sink: opts.sink } : {}),
+                    registry: opts.registry,
+                    taskId: targetId,
+                    taskAccess: resolvedAccess,
+                    ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
+                    sessionScoped: row.sessionScoped === true,
+                    ...(row.description !== undefined ? { rowDescription: row.description } : {}),
+                    ...(row.name !== undefined ? { rowName: row.name } : {}),
+                    ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
+                    ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
+                    ...(row.scope !== undefined ? { rowScope: row.scope } : {}),
+                    ...(row.parentTaskId !== undefined ? { rowParentTaskId: row.parentTaskId } : {}),
+                    ...(row.parentSessionId !== undefined ? { rowParentSessionId: row.parentSessionId } : {}),
+                    ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
+                    ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
+                });
+                const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
+                try {
+                    const safeSummary = summary !== undefined ? escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary) : undefined;
+                    const safeMessage = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, message);
+                    const marker = await resume(`${fromPrefix}${safeSummary ? `[${safeSummary}] ${safeMessage}` : safeMessage}`);
+                    return {
+                        content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
+                            `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
+                        details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, ...(summary !== undefined ? { summary } : {}) },
+                    };
+                }
+                catch (e) {
+                    const code = e?.code;
+                    const text = code === "resume.retain_off"
+                        ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
+                        : code === "resume.evicted"
+                            ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
+                            : code === "resume.session_not_found"
+                                ? `${who}'s session no longer exists — relaunch a new agent instead.`
+                                : code === "resume.cap"
+                                    ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
+                                    : code === "steering.still_running"
+                                        ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
+                                        : code === "resume.row_gone"
+                                            ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
+                                            : `${e instanceof Error ? e.message : String(e)}`;
+                    return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
+                }
+            });
         },
     });
 }

package/dist/agents/subagent.d.ts

@@ -5,16 +5,14 @@ import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
 export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
-import { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry } from "./retain-ledger.js";
-export { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry };
-export { AGENT_TRANSCRIPT_TOOL_NAME, createAgentTranscriptTool, type AgentTranscriptToolOptions } from "./agent-transcript-tool.js";
-export { SEND_MESSAGE_TOOL_NAME, createSendMessageTool, type SendMessageToolOptions } from "./send-message-tool.js";
+import { SubagentRetainLedger } from "./retain-ledger.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
 export declare function notifyResultField(result: string | undefined): string | undefined;
 export declare function inheritedManifestScopeFor(snapshot: readonly unknown[] | undefined): RunInternals["inheritedManifestScope"];
 export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
 export declare const LEGACY_SUBAGENT_TOOL_NAME = "Task";
 export declare const EXTRA_TOOLS_MAX_FACTORY_CALLS_PER_TREE = 64;
+export declare const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
 export declare const EXTRA_TOOLS_FAILED_NOTE = "note: extraTools evaluation failed \u2014 the injected tool set was skipped for this spawn.";
 export declare const EXTRA_TOOLS_BUDGET_NOTE = "note: extraTools evaluation was skipped \u2014 this spawn tree exhausted its factory-call budget (64); no dynamic tools were injected for this spawn.";
 export interface SubagentToolStats {
@@ -127,8 +125,17 @@ export interface SubagentSpawnContext {
     agentType?: string;
     depth: number;
 }
+export declare function normalizeSubagentType(value: string): string;
 export declare const SUBAGENT_SYSTEM_NOTE: string;
 export declare const FORK_DIRECTIVE_FRAME = "<fork-boilerplate>\nYou are a worker fork. The transcript above is the parent's history \u2014 inherited reference, not your situation. You are NOT a continuation of that agent. Execute ONE directive, then stop.\n\nHard rules:\n- Do NOT spawn subagents with the Agent tool. The \"default to forking\" guidance is for the parent; you ARE the fork, execute directly.\n- One shot: report once and stop. No follow-up questions, no proposed next steps, no waiting for the user.\n\nGuidelines (your directive may override any of these):\n- Stay in scope. Other forks may be handling adjacent work; if you spot something outside your directive, note it in a sentence and move on.\n- Open with one line restating your task, so the parent can spot scope drift at a glance.\n- Be concise \u2014 as short as the answer allows, no shorter. Plain text, no preamble, no meta-commentary.\n- If you committed changes, list the paths and commit hashes in your report.\n</fork-boilerplate>\n\nYour directive: ";
+export declare function forkWorktreeTranslationNote(parentCwd: string | undefined, worktreeDir: string): string;
+export declare function asyncLaunchedReceipt(p: {
+    taskId: string;
+    workingLine: string;
+    notify: boolean;
+    oneShot?: boolean;
+    notes?: (string | undefined)[];
+}): string;
 export declare function createSubagentTool(opts: SubagentToolOptions): ToolSpec;
 export declare function agentToolsNote(def: {
     allowTools?: string[];