@agentclientprotocol/claude-agent-acp 0.89.2-preview.2 → 0.89.2-preview.20

package/dist/native-subagents.js

@@ -1,3 +1,4 @@
+import { RequestError } from "@agentclientprotocol/sdk";
 import { AIR_SUBAGENT_KEY, airExtensionMeta } from "./air-extension.js";
 const MAX_PENDING_PARENTS = 64;
 const MAX_PENDING_UPDATES = 256;
@@ -14,6 +15,8 @@ export class NativeSubagentRuntime {
     publish;
     logger;
     enabled;
+    /** The form of the child sessions; see {@link SubagentForm}. */
+    form;
     children;
     taskByToolUse;
     parentByToolUse;
@@ -27,15 +30,19 @@ export class NativeSubagentRuntime {
      */
     childByToolCall = new Map();
     taskFinishPromises = new Map();
+    /** The RFD form: the session that made each SendMessage call. */
+    senderByToolUse = new Map();
     generationByTaskId = new Map();
     pending = new Map();
     pendingCount = 0;
-    constructor(enabled, rootSessionId, session, publish, logger) {
+    /** `form` is undefined for a client without native subagent sessions. */
+    constructor(form, rootSessionId, session, publish, logger) {
         this.rootSessionId = rootSessionId;
         this.session = session;
         this.publish = publish;
         this.logger = logger;
-        this.enabled = enabled;
+        this.form = form;
+        this.enabled = form !== undefined;
         this.children = session.nativeSubagentsByTaskId ??= new Map();
         this.taskByToolUse = session.nativeSubagentTaskIdByToolUseId ??= new Map();
         this.parentByToolUse = session.nativeSubagentParentByToolUseId ??= new Map();
@@ -46,6 +53,12 @@ export class NativeSubagentRuntime {
         }
     }
     async route(notification, deliver, forcedSessionId) {
+        const routed = await this.routeUpdate(notification, deliver, forcedSessionId);
+        if (routed && this.form === "rfd")
+            this.rememberSendMessage(routed);
+        return routed;
+    }
+    async routeUpdate(notification, deliver, forcedSessionId) {
         const { update } = notification;
         const claudeMeta = update._meta?.claudeCode;
         const isControl = isNativeSubagentControlUpdate(update);
@@ -60,28 +73,43 @@ export class NativeSubagentRuntime {
             if (identity) {
                 this.identityByToolUse.set(toolCallId, mergeSubagentIdentity(this.identityByToolUse.get(toolCallId), identity));
             }
+            const parentChild = claudeMeta?.parentToolUseId
+                ? this.childByParentToolUse.get(claudeMeta.parentToolUseId)
+                : undefined;
             const parentSessionId = claudeMeta?.parentToolUseId
-                ? this.childByParentToolUse.get(claudeMeta.parentToolUseId)?.sessionId
+                ? parentChild?.sessionId
                 : this.rootSessionId;
-            this.parentByToolUse.set(toolCallId, parentSessionId ?? this.rootSessionId);
+            // The RFD form: a call made inside a child that is not announced yet
+            // establishes no parent, because the RFD forbids announcing its child
+            // under the root or before that child. The update is buffered below
+            // under the child's tool use, and routed again, with the child as the
+            // parent, once the child is announced.
+            const parentPending = this.form === "rfd" && !!claudeMeta?.parentToolUseId && !parentChild?.announced;
             const child = this.childByParentToolUse.get(toolCallId);
-            if (child && !child.announced) {
-                child.parentSessionId = parentSessionId ?? this.rootSessionId;
-                applySubagentIdentity(child, this.identityByToolUse.get(toolCallId));
-                await announceNativeSubagent(child, this.publish);
-                for (const pending of this.takePending(toolCallId))
-                    await deliver(pending);
+            if (!parentPending) {
+                this.parentByToolUse.set(toolCallId, parentSessionId ?? this.rootSessionId);
+                if (child && !child.announced) {
+                    child.parentSessionId = parentSessionId ?? this.rootSessionId;
+                    applySubagentIdentity(child, this.identityByToolUse.get(toolCallId));
+                    await this.announce(child);
+                    for (const pending of this.takePending(toolCallId))
+                        await deliver(pending);
+                }
             }
-            if (!child && isFailedToolCallUpdate(update)) {
-                this.takePending(toolCallId);
-                const initial = this.controlByToolUse.get(toolCallId);
-                this.cleanupControl(toolCallId);
-                if (forcedSessionId) {
-                    return { ...notification, sessionId: forcedSessionId };
+            if (this.form === "air") {
+                if (!child && isFailedToolCallUpdate(update)) {
+                    this.takePending(toolCallId);
+                    const initial = this.controlByToolUse.get(toolCallId);
+                    this.cleanupControl(toolCallId);
+                    if (forcedSessionId) {
+                        return { ...notification, sessionId: forcedSessionId };
+                    }
+                    return failedControlFallback(initial, notification, parentSessionId ?? this.rootSessionId);
                 }
-                return failedControlFallback(initial, notification, parentSessionId ?? this.rootSessionId);
+                return forcedSessionId ? { ...notification, sessionId: forcedSessionId } : null;
             }
-            return forcedSessionId ? { ...notification, sessionId: forcedSessionId } : null;
+            // The RFD form: the Agent/Task tool call is the parent's record of the
+            // delegation, so it stays a tool call of the session that made it.
         }
         const toolCallId = update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update"
             ? update.toolCallId
@@ -112,6 +140,13 @@ export class NativeSubagentRuntime {
     async taskStarted(task, deliver) {
         if (!this.enabled)
             return;
+        const known = this.form === "rfd" ? this.children.get(task.taskId) : undefined;
+        if (known) {
+            // A child keeps its session for every delegation to it. The SDK starts
+            // a resumed agent again under the id of the call that resumed it.
+            await this.resumeChild(known, task.taskId, promptText(task.prompt), task.toolUseId ?? undefined, deliver);
+            return;
+        }
         if (!task.subagentType) {
             if (task.toolUseId) {
                 this.takePending(task.toolUseId);
@@ -135,6 +170,7 @@ export class NativeSubagentRuntime {
             name: subagentDisplayName(identity?.name, identity?.description ?? task.description, identity?.subagentType ?? task.subagentType, task.taskId),
             task: subagentDescription(identity?.prompt ?? task.prompt, identity?.description ?? task.description),
             ...promptField(promptText(task.prompt) ?? identity?.prompt),
+            ...rfdLabels(identity?.name, identity?.subagentType ?? task.subagentType, identity?.description ?? task.description),
         }, !!knownParentSessionId || !task.toolUseId, deliver);
     }
     /**
@@ -143,6 +179,10 @@ export class NativeSubagentRuntime {
      * running `task_updated` patch or a SendMessage `resumedAgentId` is the
      * signal. A child that did not finish is not changed. The `prompt` is the
      * SendMessage text that resumed the child, when the adapter knows it.
+     *
+     * In the RFD form, the running patch only reports that the child runs: its
+     * prompt is a guess (the latest SendMessage to the agent), and the
+     * `task_started` or the SendMessage result carries the delegation.
      */
     async taskResumed(taskId, deliver, prompt) {
         if (!this.enabled)
@@ -153,6 +193,10 @@ export class NativeSubagentRuntime {
         const finishing = this.taskFinishPromises.get(taskId) ?? previous.terminalPromise;
         if (finishing)
             await finishing.catch(() => { });
+        if (this.form === "rfd") {
+            await this.resumeChild(previous, taskId, undefined, undefined, deliver);
+            return;
+        }
         if (this.children.get(taskId) !== previous || previous.terminalState === undefined)
             return;
         await this.openGeneration(taskId, previous, {
@@ -163,26 +207,97 @@ export class NativeSubagentRuntime {
             ...promptField(promptText(prompt)),
         }, true, deliver);
     }
-    async finishTask(taskId, status, deliver, toolUseId) {
+    /**
+     * The SDK reports in a SendMessage result that the call `toolUseId`, with
+     * the message `prompt`, resumed the agent `taskId`. AIR's draft treats it as
+     * any resume signal. In the RFD form, the call is the delegation, which the
+     * child takes unless its run already ended: the result can arrive after it.
+     */
+    async sendMessageResumed(taskId, deliver, prompt, toolUseId) {
+        if (this.form !== "rfd")
+            return this.taskResumed(taskId, deliver, prompt);
+        const child = this.children.get(taskId);
+        if (!child)
+            return;
+        const finishing = this.taskFinishPromises.get(taskId);
+        if (finishing)
+            await finishing.catch(() => { });
+        if (this.isEndedDelegation(taskId, toolUseId))
+            return;
+        await this.resumeChild(child, taskId, promptText(prompt), toolUseId, deliver);
+    }
+    /**
+     * The RFD form: whether the run of the call `toolUseId` that delegated to
+     * the child `taskId` already ended. AIR's draft has no such runs.
+     */
+    isEndedDelegation(taskId, toolUseId) {
+        if (this.form !== "rfd" || !toolUseId)
+            return false;
+        return this.children.get(taskId)?.endedRuns?.has(toolUseId) ?? false;
+    }
+    /**
+     * The RFD form: whether `toolUseId` is an earlier delegation of the child
+     * `taskId`, whose end does not end the current one. AIR's draft has no
+     * such delegations.
+     */
+    isStaleEnd(taskId, toolUseId) {
+        if (this.form !== "rfd" || !toolUseId)
+            return false;
+        const child = this.children.get(taskId);
+        return (!!child &&
+            child.parentToolUseId !== undefined &&
+            toolUseId !== child.parentToolUseId &&
+            this.childByParentToolUse.get(toolUseId) === child);
+    }
+    /**
+     * Reports that the SDK ended the task's work. `end` has what the SDK says
+     * about it: its text for a failure, and its reason for an unusual end.
+     */
+    async finishTask(taskId, status, deliver, toolUseId, end) {
         if (!this.enabled)
             return;
         const state = nativeSubagentState(status);
         const child = toolUseId ? this.childByParentToolUse.get(toolUseId) : this.children.get(taskId);
         if (child && toolUseId && this.taskByToolUse.get(toolUseId) !== taskId)
             return;
-        if (!state || !child || child.terminalState !== undefined)
+        if (!state || !child)
             return;
+        if (this.form === "rfd") {
+            if (this.isStaleEnd(taskId, toolUseId))
+                return;
+            if (!child.announced && !child.announcePromise) {
+                this.withdraw(taskId, child);
+                return;
+            }
+        }
         const existing = this.taskFinishPromises.get(taskId);
-        if (existing)
-            return existing;
+        if (existing) {
+            await existing;
+            if (this.form === "rfd")
+                await this.supplyError(child, state, end?.error);
+            return;
+        }
+        if (this.form === "air" ? child.terminalState !== undefined : child.workState === "idle") {
+            if (this.form === "rfd")
+                await this.supplyError(child, state, end?.error);
+            return;
+        }
         const finish = Promise.resolve().then(async () => {
             try {
-                await announceNativeSubagent(child, this.publish);
+                await this.announce(child);
                 if (child.parentToolUseId) {
                     for (const pending of this.takePending(child.parentToolUseId))
                         await deliver(pending);
                 }
-                await finishNativeSubagent(this.session, taskId, state, this.publish);
+                if (this.form === "rfd") {
+                    await this.reportState(child, rfdEndState(state, end));
+                    child.missingError = state === "failed" && !end?.error && !end?.unexplained;
+                    if (child.parentToolUseId)
+                        (child.endedRuns ??= new Set()).add(child.parentToolUseId);
+                }
+                else {
+                    await finishNativeSubagent(this.session, taskId, state, this.publish);
+                }
             }
             finally {
                 if (child.parentToolUseId) {
@@ -199,12 +314,20 @@ export class NativeSubagentRuntime {
                 this.taskFinishPromises.delete(taskId);
         }
     }
+    /**
+     * Ends every child that still runs, because the stream ended or the
+     * conversation was reset. AIR's draft reports `state` for each. In the RFD
+     * form the cause of each child's end is unknown, so it is idle with no stop
+     * reason: a child that a cancel stopped already reported it from the SDK's
+     * events, and a background child that outlived the cancel was not cancelled.
+     */
     async finishAll(state, deliver) {
         const errors = [];
+        const end = this.form === "rfd" ? { unexplained: true } : undefined;
         try {
             for (const taskId of [...this.children.keys()].reverse()) {
                 try {
-                    await this.finishTask(taskId, state, deliver);
+                    await this.finishTask(taskId, state, deliver, undefined, end);
                 }
                 catch (error) {
                     errors.push(error);
@@ -223,15 +346,120 @@ export class NativeSubagentRuntime {
         if (errors.length > 1)
             throw new AggregateError(errors, "Failed to finish native subagents");
     }
+    /**
+     * The parent session got `session/cancel`. AIR's draft ends every child as
+     * cancelled here. The RFD form reports nothing: acknowledging a cancel is no
+     * evidence that a child stopped. Claude Code's interrupt stops the
+     * foreground children that the turn waits on and, currently, background
+     * children too, and the SDK's task events report each as cancelled. A child
+     * that keeps running keeps its open requests
+     * (agentclientprotocol/agent-client-protocol#2308).
+     */
+    async parentCancelled(deliver) {
+        if (this.form === "air")
+            await this.finishAll("cancelled", deliver);
+    }
+    /**
+     * Runs `request`, a permission or question request of the session
+     * `sessionId`. In the RFD form, a child waiting on it is `requires_action`
+     * until its last open request ends.
+     */
+    async awaitingUser(sessionId, request) {
+        const child = this.form === "rfd" ? this.childOfSession(sessionId) : undefined;
+        if (!child?.announced)
+            return request();
+        child.openRequests = (child.openRequests ?? 0) + 1;
+        if (child.openRequests === 1 && child.workState === "running") {
+            await this.reportState(child, { state: "requires_action" }).catch((error) => this.logger.log(`Failed to report that subagent ${child.sessionId} waits: ${error}`));
+        }
+        try {
+            return await request();
+        }
+        finally {
+            child.openRequests = (child.openRequests ?? 1) - 1;
+            if (child.openRequests === 0 && child.workState === "requires_action") {
+                await this.reportState(child, { state: "running" }).catch((error) => this.logger.log(`Failed to report that subagent ${child.sessionId} runs: ${error}`));
+            }
+        }
+    }
     discardPending(parentToolUseId) {
         this.takePending(parentToolUseId);
     }
     /**
-     * Routes an update to the child session. An update of a finished child is
-     * dropped: it never goes to the root session.
+     * The RFD form: the child runs again, and keeps its session. `toolUseId` is
+     * the call that delegated, usually a SendMessage: the SDK runs the resumed
+     * work under its id, so it becomes the child's current delegation, whose
+     * end ends the run, and its prompt is the message with that id. A child
+     * that is already working only takes the delegation; a prompt already in
+     * its transcript is not sent again. A child that was never announced is
+     * not changed.
+     */
+    async resumeChild(child, taskId, prompt, toolUseId, deliver) {
+        if (!child.announced)
+            return;
+        if (toolUseId && toolUseId !== child.parentToolUseId) {
+            this.taskByToolUse.set(toolUseId, taskId);
+            this.childByParentToolUse.set(toolUseId, child);
+            child.parentToolUseId = toolUseId;
+        }
+        if (!isWorking(child)) {
+            await this.reportState(child, {
+                state: child.openRequests ? "requires_action" : "running",
+            });
+        }
+        if (prompt && toolUseId) {
+            await publishPrompt(child, prompt, toolUseId, this.senderByToolUse.get(toolUseId), this.publish);
+        }
+        for (const pending of toolUseId ? this.takePending(toolUseId) : [])
+            await deliver(pending);
+    }
+    /**
+     * The RFD form: a child that ends before its parent is known stays
+     * unexposed, since the RFD forbids guessing its parent. Its buffered updates
+     * are dropped, and it is forgotten, so a late frame does not announce it.
+     * (Buffering until that frame would also meet the RFD, but the frame comes
+     * before the task in the SDK's order, so a child ending without it is rare.)
+     */
+    withdraw(taskId, child) {
+        this.children.delete(taskId);
+        if (child.parentToolUseId) {
+            this.takePending(child.parentToolUseId);
+            this.cleanupControl(child.parentToolUseId);
+            this.childByParentToolUse.delete(child.parentToolUseId);
+            this.taskByToolUse.delete(child.parentToolUseId);
+        }
+    }
+    /**
+     * The RFD form: a later event of a failure can carry the SDK's error text
+     * that the reported idle snapshot lacks.
+     */
+    async supplyError(child, state, error) {
+        if (state !== "failed" || !error || !child.missingError)
+            return;
+        await this.reportState(child, rfdEndState("failed", { error }));
+    }
+    /** Announces `child` in the client's form. A runtime without one never does. */
+    async announce(child) {
+        if (this.form)
+            await announceNativeSubagent(child, this.publish, this.form);
+    }
+    /** The RFD form: publishes the work state of `child` on its parent. */
+    async reportState(child, state) {
+        child.workState = state.state;
+        child.missingError = false;
+        await this.publish({
+            sessionId: child.parentSessionId,
+            update: { sessionUpdate: "subagent_update", sessionId: child.sessionId, state },
+        });
+    }
+    /**
+     * Routes an update to the child session. It never goes to the root session:
+     * in AIR's draft, an update of a finished child is dropped.
      */
     toChild(child, notification, toolCallId) {
-        if (child.terminalState !== undefined || child.terminalPromise) {
+        // AIR's draft ends a child for good. In the RFD form an idle child is
+        // reusable, and its background work can still report.
+        if (this.form === "air" && (child.terminalState !== undefined || child.terminalPromise)) {
             this.logger.log(`Session ${this.rootSessionId}: ignoring late update for terminal subagent ${child.sessionId}`);
             return null;
         }
@@ -245,10 +473,11 @@ export class NativeSubagentRuntime {
      * tool call when the work started. An async task can outlive that child: a
      * subagent can start a background command and end its turn. So the route
      * still sends `async_task_spawned`, `async_task_progress` and
-     * `async_task_state_update` to the child generation after it finished. The route drops every other update
-     * after the child finished. `undefined` means that the root session owns the
-     * tool call. `eagerSessionId` is the session where a permission request
-     * created the tool call before the stream routed it.
+     * `async_task_state_update` to the child generation after it finished. In
+     * AIR's draft, the route drops every other update after the child finished;
+     * in the RFD form, an idle child gets them all. `undefined` means that the
+     * root session owns the tool call. `eagerSessionId` is the session where a
+     * permission request created the tool call before the stream routed it.
      */
     routeOfToolCall(toolCallId, eagerSessionId) {
         if (!this.enabled)
@@ -260,6 +489,25 @@ export class NativeSubagentRuntime {
                 ? { ...notification, sessionId: owner.sessionId }
                 : this.toChild(owner, notification, undefined)));
     }
+    /**
+     * The RFD form: remembers the session that made a SendMessage call, the
+     * sender of the prompt when the call resumes a child.
+     */
+    rememberSendMessage(notification) {
+        const { update } = notification;
+        if (update.sessionUpdate !== "tool_call")
+            return;
+        const claudeMeta = update._meta?.claudeCode;
+        if (claudeMeta?.toolName !== "SendMessage")
+            return;
+        this.senderByToolUse.delete(update.toolCallId);
+        this.senderByToolUse.set(update.toolCallId, notification.sessionId);
+        if (this.senderByToolUse.size > MAX_CHILD_TOOL_CALLS) {
+            const oldest = this.senderByToolUse.keys().next().value;
+            if (oldest !== undefined)
+                this.senderByToolUse.delete(oldest);
+        }
+    }
     rememberToolCallOwner(toolCallId, child) {
         this.childByToolCall.delete(toolCallId);
         this.childByToolCall.set(toolCallId, child);
@@ -288,6 +536,7 @@ export class NativeSubagentRuntime {
         this.controlByToolUse.clear();
         this.childByParentToolUse.clear();
         this.taskFinishPromises.clear();
+        this.senderByToolUse.clear();
         this.generationByTaskId.clear();
         this.pending.clear();
         this.pendingCount = 0;
@@ -353,10 +602,20 @@ export class NativeSubagentRuntime {
         }
         if (!announce)
             return;
-        await announceNativeSubagent(child, this.publish);
+        await this.announce(child);
         for (const pending of toolUseId ? this.takePending(toolUseId) : [])
             await deliver(pending);
     }
+    /**
+     * The ACP session id of a child: the SDK agent id, and in AIR's draft a
+     * generation suffix for each resume. The RFD needs it unique within the
+     * connection and never under two parents. Agent ids are random, and an
+     * agent keeps its parent, so only a fork could repeat one under another
+     * root. That holds today because the SDK's `forkSession` copies no
+     * `subagents/` history, so a fork cannot resume an agent of the original.
+     * If a fork ever can, the RFD requires remapping the copied ids, for
+     * example by deriving the child id from the root session id.
+     */
     nextChildSessionId(taskId, previous) {
         if (!previous) {
             this.generationByTaskId.set(taskId, 1);
@@ -367,12 +626,37 @@ export class NativeSubagentRuntime {
         return `${taskId}:generation:${generation}`;
     }
 }
-export async function announceNativeSubagent(child, publish) {
+/**
+ * Announces the child on its parent, once, before any update of the child.
+ * The RFD form announces it as running and then sends the prompt as the
+ * first message of the child. The child gets no capabilities, so the client
+ * may not cancel or otherwise change it.
+ */
+export async function announceNativeSubagent(child, publish, form) {
     if (child.announced)
         return;
     if (child.announcePromise)
         return child.announcePromise;
     const announce = Promise.resolve().then(async () => {
+        if (form === "rfd") {
+            child.workState = "running";
+            await publish({
+                sessionId: child.parentSessionId,
+                update: {
+                    sessionUpdate: "subagent_update",
+                    sessionId: child.sessionId,
+                    ...(child.title ? { title: child.title } : {}),
+                    ...(child.description ? { description: child.description } : {}),
+                    state: { state: "running" },
+                },
+            });
+            child.announced = true;
+            // The immediate parent made the Agent/Task call that launched the child.
+            if (child.prompt) {
+                await publishPrompt(child, child.prompt, child.parentToolUseId, child.parentSessionId, publish);
+            }
+            return;
+        }
         await publish({
             sessionId: child.parentSessionId,
             update: {
@@ -402,7 +686,7 @@ export async function finishNativeSubagent(session, taskId, state, publish) {
     if (child.terminalPromise)
         return child.terminalPromise;
     const finish = Promise.resolve().then(async () => {
-        await announceNativeSubagent(child, publish);
+        await announceNativeSubagent(child, publish, "air");
         await publish({
             sessionId: child.parentSessionId,
             update: {
@@ -422,6 +706,85 @@ export async function finishNativeSubagent(session, taskId, state, publish) {
             child.terminalPromise = undefined;
     }
 }
+/**
+ * The RFD form: a message to the child, in the child's transcript (its
+ * incoming view). Its id is the id of the tool use that sent it, the
+ * Agent/Task call or a SendMessage, so a prompt whose id is already in the
+ * transcript is the same delegation and is not sent again. `sender` is the
+ * session that made that call, when known.
+ */
+async function publishPrompt(child, prompt, toolUseId, sender, publish) {
+    child.promptIds ??= new Set();
+    const messageId = toolUseId ?? `${child.sessionId}:prompt:${child.promptIds.size + 1}`;
+    if (child.promptIds.has(messageId))
+        return;
+    child.promptIds.add(messageId);
+    await publish({
+        sessionId: child.sessionId,
+        update: {
+            sessionUpdate: "session_message",
+            messageId,
+            ...(sender ? { senderSessionId: sender } : {}),
+            recipientSessionId: child.sessionId,
+            content: [{ type: "text", text: prompt }],
+        },
+    });
+}
+/** The RFD form: whether the child's foreground work is in progress. */
+function isWorking(child) {
+    return child.workState === "running" || child.workState === "requires_action";
+}
+/**
+ * The RFD form: the work state at the end of a child's work.
+ *
+ * A failure is idle with the `error` stop reason and, when the SDK gives its
+ * text, the JSON-RPC `error`, as the RFD asks: a v1 child has no prompt
+ * response, so this is how a client learns that its work failed. The error is
+ * an internal error, as for a failed turn on the v2 surface.
+ *
+ * A task that a worker restart orphaned, or that was still running when the
+ * stream ended, is idle with no stop reason: its work ended, but the adapter
+ * did not see a cancellation or a failure, which the RFD forbids claiming.
+ */
+export function rfdEndState(state, end) {
+    if (end?.unexplained || end?.reason === "worker_restart")
+        return { state: "idle" };
+    switch (state) {
+        case "completed":
+            return { state: "idle", stopReason: "end_turn" };
+        case "cancelled":
+            return { state: "idle", stopReason: "cancelled" };
+        case "failed":
+            return {
+                state: "idle",
+                stopReason: "error",
+                ...(end?.error
+                    ? { error: { code: RequestError.internalError().code, message: end.error } }
+                    : {}),
+            };
+        default:
+            // "disconnected": the child can no longer be observed.
+            return { state: "unknown" };
+    }
+}
+/**
+ * The RFD form: the parent's labels for a child. The title is the agent's
+ * name, with its role after it when both are known, else the role. The
+ * description is the task's short description, never the prompt.
+ */
+export function rfdLabels(name, role, description) {
+    const agentName = nonBlankString(name);
+    const agentRole = nonBlankString(role);
+    const title = agentName && agentRole && agentName !== agentRole
+        ? `${agentName} (${agentRole})`
+        : (agentName ?? agentRole);
+    const text = nonBlankString(description);
+    return {
+        ...(title ? { title } : {}),
+        ...(agentRole ? { role: agentRole } : {}),
+        ...(text ? { description: text } : {}),
+    };
+}
 /**
  * The agent id that a successful SendMessage result resumed. The SDK puts it
  * in `tool_use_result.resumedAgentId` when a finished agent runs again.
@@ -438,22 +801,34 @@ export function resumedNativeSubagentId(toolUseResult) {
  * carried the resume. Otherwise the latest SendMessage call to `agentId` counts.
  */
 export function sendMessageResumePrompt(toolUses, agentId, resultToolUseIds = []) {
+    return sendMessageResume(toolUses, agentId, resultToolUseIds)?.text;
+}
+/**
+ * The SendMessage call that resumed the agent `agentId`, and its text when it
+ * has one; see {@link sendMessageResumePrompt}. The call is known even
+ * without text, so a late result still names the delegation it reports.
+ */
+export function sendMessageResume(toolUses, agentId, resultToolUseIds = []) {
+    let withoutText;
     for (const toolUseId of resultToolUseIds) {
         const toolUse = toolUses[toolUseId];
         if (toolUse?.name !== "SendMessage")
             continue;
         const text = promptText(toolUse.input?.message);
         if (text)
-            return text;
+            return { toolUseId, text };
+        withoutText ??= toolUseId;
     }
     if (resultToolUseIds.length > 0)
-        return undefined;
-    for (const toolUse of Object.values(toolUses).reverse()) {
+        return withoutText ? { toolUseId: withoutText } : undefined;
+    for (const [toolUseId, toolUse] of Object.entries(toolUses).reverse()) {
         if (toolUse?.name !== "SendMessage")
             continue;
         const input = toolUse.input;
-        if (input?.to === agentId)
-            return promptText(input.message);
+        if (input?.to !== agentId)
+            continue;
+        const text = promptText(input.message);
+        return text ? { toolUseId, text } : { toolUseId };
     }
     return undefined;
 }
@@ -596,6 +971,10 @@ function applySubagentIdentity(child, identity) {
         child.task = subagentDescription(identity.prompt, identity.description);
     }
     child.prompt ??= identity.prompt;
+    const labels = rfdLabels(identity.name, identity.subagentType ?? child.role, identity.description);
+    child.title = labels.title ?? child.title;
+    child.role = labels.role ?? child.role;
+    child.description = labels.description ?? child.description;
 }
 /** The prompt text unchanged, or `undefined` when it is not a non-blank string. */
 function promptText(value) {

package/dist/settings.d.ts

@@ -19,6 +19,7 @@ export declare class SettingsManager {
     private cwd;
     private effective;
     private managedDeniedModels;
+    private managedApiKeyHelper?;
     private watchers;
     private onChange?;
     private logger;
@@ -53,6 +54,11 @@ export declare class SettingsManager {
      * Returns the current merged settings
      */
     getSettings(): Settings;
+    /**
+     * The `apiKeyHelper` the CLI runs: managed settings outrank the `--settings`
+     * override, which outranks the user/project/local files.
+     */
+    getApiKeyHelper(settingsOverride?: Settings): string | undefined;
     /**
      * `deniedModels` entries from the managed tier, the only tier the CLI
      * honors them from.