@lucascouts/claude-agent-acp-plus 0.33.0 → 0.34.0

package/dist/acp-agent.js

@@ -1,5 +1,5 @@
 import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk/unstable";
-import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { deleteSession, getSessionMessages, getSubagentMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.js";
 import { sanitizeTitle, SessionTitles } from "./session-titles.js";
 import { readResumedPermissionMode, readResumedSession, } from "./resumed-session.js";
@@ -36,6 +36,9 @@ import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./u
 import { acceptedPlanToolResult, ExitPlanCoordinator, exitPlanModeRawOutput, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
 import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID, PLAN_UPDATES_CONFIG_ID, } from "./session-config-ids.js";
 import { withPrecompactHistory } from "./compacted-history.js";
+import { subagentForm } from "./acp-subagents.js";
+import { ChildSessionRouter, childStopReasonOf } from "./child-sessions.js";
+import { readSubagentLaunches } from "./child-session-history.js";
 import { findTranscript } from "./transcript-path.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { AccountUsageTracker } from "./account-usage.js";
@@ -157,6 +160,9 @@ export const TASKS_OUTPUT_METHOD = "_claude/tasks/output";
 export const TASKS_CAPABILITY_KEY = TASKS_META_KEY;
 /** Version 2 (story 041) adds `hasOutput`, `tail` and `_claude/tasks/output`. */
 export const TASKS_CAPABILITY_VERSION = TASKS_CONTRACT_VERSION;
+/** Version 3: a subagent entry names its child session (`childSessionId`).
+ *  Only a client on the subagents RFD gets it (story 065, R6.2, R6.3). */
+export const TASKS_RFD_CONTRACT_VERSION = 3;
 /** Refresh the account quota windows of one session now, on demand. Params
  *  {@link UsageRefreshRequest}, result {@link UsageRefreshResponse}. The windows
  *  themselves arrive the way they always do — one `usage_update` per window,
@@ -400,6 +406,69 @@ function stripSubagentTextAndThinking(content) {
 }
 /** A cached tool call's `description` input, when it is a string — or, for a
  *  shell call, its `command_description` alias (CLI 2.1.295+, upstream #1330). */
+/** What a child session is announced with, read from `task_started` and the
+ *  Agent call it names (story 065, R2.1): the Agent call's `name` or the
+ *  subagent type as the title, its short description, and its prompt. */
+function subagentLaunchOf(parentSessionId, session, message) {
+    const input = (session.toolUseCache[message.tool_use_id ?? ""]?.input ?? {});
+    const name = typeof input.name === "string" && input.name.trim() ? input.name : undefined;
+    const prompt = message.prompt ?? (typeof input.prompt === "string" ? input.prompt : undefined);
+    return {
+        parentSessionId,
+        launcherTaskId: message.parent_task_id,
+        toolUseId: message.tool_use_id,
+        agentId: message.task_id,
+        title: name ?? message.subagent_type ?? message.description,
+        description: message.description,
+        prompt,
+        cancellable: typeof session.query.stopTask === "function",
+    };
+}
+/** A child read back from a transcript, in the shape `ChildSessionRouter`
+ *  announces: the same title rule as a live launch (`subagentLaunchOf`). */
+function childLaunchOf(parentSessionId, session, toolUseId, record, input) {
+    const text = (value) => (typeof value === "string" && value.trim() ? value : undefined);
+    const description = record.description ?? text(input.description) ?? "";
+    return {
+        parentSessionId,
+        launcherTaskId: record.launcherAgentId,
+        toolUseId,
+        agentId: record.agentId,
+        title: record.name ?? text(input.name) ?? record.agentType ?? (description || "Subagent"),
+        description,
+        prompt: text(input.prompt),
+        // History, not a task the CLI holds: no Stop until it runs again, when its
+        // live launch advertises what the SDK can stop (design.md, Security).
+        cancellable: false,
+    };
+}
+/** The text of a user message whose content is a string or one text block. */
+function userText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content) && content.length === 1 && content[0]?.type === "text") {
+        return content[0].text;
+    }
+    return undefined;
+}
+/** A child's permission request ended by `session/cancel` on that child. */
+class ChildSessionCancelled extends Error {
+    constructor(childId) {
+        super(`Subagent ${childId} was cancelled`);
+    }
+}
+/** `client` with every `session/update` passed through the child router. */
+function withChildRouting(client, router) {
+    return new Proxy(client, {
+        get(target, property) {
+            if (property === "sessionUpdate") {
+                return (notification) => target.sessionUpdate(router.route(notification));
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
 function toolDescriptionOf(cache, toolUseId) {
     if (typeof toolUseId !== "string")
         return undefined;
@@ -772,6 +841,12 @@ export class ClaudeAcpAgent {
     sessions;
     client;
     clientCapabilities;
+    /** Set at `initialize`: `rfd` when the client declared `clientCapabilities.subagents`. */
+    subagentForm;
+    /** Present only in the RFD form: moves subagent traffic to child sessions (story 065). */
+    childSessions;
+    /** Open permission requests of each child, aborted when that child is cancelled. */
+    childAsks = new Map();
     logger;
     sessionModes;
     gatewayAuthRequest;
@@ -843,6 +918,16 @@ export class ClaudeAcpAgent {
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
+        this.subagentForm = subagentForm(request.clientCapabilities);
+        if (this.subagentForm === "rfd" && !this.childSessions) {
+            const direct = this.client;
+            const router = new ChildSessionRouter((notification) => direct.sessionUpdate(notification), (line) => this.logger.log(line));
+            this.childSessions = router;
+            // The one place every `session/update` crosses — the consumer's
+            // `sendUpdate`, the task feed, hooks, the classifier — so a subagent's
+            // update cannot reach the parent by an emission site that forgot it.
+            this.client = withChildRouting(direct, router);
+        }
         // Bypasses standard auth by routing requests through a custom Anthropic-protocol gateway.
         // Only offered when the client advertises `auth._meta.gateway` capability.
         const supportsGatewayAuth = request.clientCapabilities?.auth?._meta?.gateway === true;
@@ -945,7 +1030,9 @@ export class ClaudeAcpAgent {
                     claudeCode: {
                         promptQueueing: true,
                     },
-                    [TASKS_CAPABILITY_KEY]: { version: TASKS_CAPABILITY_VERSION },
+                    [TASKS_CAPABILITY_KEY]: {
+                        version: this.childSessions ? TASKS_RFD_CONTRACT_VERSION : TASKS_CAPABILITY_VERSION,
+                    },
                     [USAGE_CAPABILITY_KEY]: { version: USAGE_CAPABILITY_VERSION },
                 },
                 promptCapabilities: {
@@ -1030,9 +1117,11 @@ export class ClaudeAcpAgent {
         return response;
     }
     async resumeSession(params) {
+        this.refuseChildSession(params.sessionId, "lifecycle");
         if (this.providerUpdate)
             await this.providerUpdate;
         const result = await this.getOrCreateSession(params);
+        await this.restoreChildSessions(params.sessionId);
         // Needs to happen after we return the session
         setTimeout(() => {
             this.sendAvailableCommandsUpdate(params.sessionId);
@@ -1040,6 +1129,7 @@ export class ClaudeAcpAgent {
         return result;
     }
     async loadSession(params) {
+        this.refuseChildSession(params.sessionId, "lifecycle");
         if (this.providerUpdate)
             await this.providerUpdate;
         const result = await this.getOrCreateSession(params);
@@ -1673,6 +1763,37 @@ export class ClaudeAcpAgent {
      *  `session/prompt`. Without the opt-in, the existing detached `prompt()` and
      *  `startedNewTurn` result are preserved for compatibility. */
     /** `_claude/tasks/stop`: stop a task the feed holds as running (R2.1, R2.2). */
+    /** `_claude/tasks` v3: each subagent entry with a child session names it
+     *  (R6.1); every other entry, and every snapshot off the RFD, is the v2
+     *  object as is (R6.3, R6.4). */
+    withChildSessionIds(snapshot) {
+        const router = this.childSessions;
+        if (!router)
+            return snapshot;
+        return {
+            ...snapshot,
+            tasks: snapshot.tasks.map((task) => task.type === "subagent" && router.isChild(task.id)
+                ? { ...task, childSessionId: task.id }
+                : task),
+        };
+    }
+    /** A child session is the parent's: its config is read-only, and it is
+     *  loaded, resumed and closed with its parent (story 065, R5.1, R5.2). Checked
+     *  first, so an id that names no session keeps the error it has today. */
+    refuseChildSession(sessionId, operation) {
+        if (!this.childSessions?.isChild(sessionId))
+            return;
+        throw RequestError.invalidParams({ sessionId }, operation === "config"
+            ? "subagent sessions are read-only and loaded with their parent"
+            : "subagent sessions are loaded with their parent and cannot be loaded, resumed or closed alone");
+    }
+    /** A subagent task ended: its child, if it has one, goes idle (story 065, R2.4). */
+    async settleChildSession(taskId, status) {
+        const stopReason = childStopReasonOf(status);
+        if (!stopReason || !this.childSessions?.isChild(taskId))
+            return;
+        await this.childSessions.settle(taskId, stopReason);
+    }
     async stopTask(params) {
         const { sessionId, taskId } = params;
         return this.taskAction(TASKS_STOP_METHOD, sessionId, `taskId=${logValue(taskId)}`, async (session) => {
@@ -3413,6 +3534,9 @@ export class ClaudeAcpAgent {
                                 if (message.subagent_type && session.activeTurn && !session.activeTurn.settled) {
                                     (session.activeTurn.spawnedTaskIds ??= new Set()).add(message.task_id);
                                 }
+                                if (this.childSessions && message.subagent_type && message.tool_use_id) {
+                                    await this.childSessions.launch(subagentLaunchOf(params.sessionId, session, message));
+                                }
                                 // The spawning tool call's own `description` labels a shell
                                 // task instead of its command line. Read it now: the cache
                                 // entry is pruned at `tool_result`, which for a background
@@ -3427,6 +3551,7 @@ export class ClaudeAcpAgent {
                                 // The task settled — no further tool calls can originate
                                 // from it, so its registry entry can be dropped.
                                 session.liveBackgroundTasks.delete(message.task_id);
+                                await this.settleChildSession(message.task_id, message.status);
                                 await endBackgroundTerminal(message.task_id, backgroundExitCode(message.status, message.summary));
                                 armDrainGrace();
                                 if (session.taskFeed && session.taskFeedPublisher) {
@@ -3452,6 +3577,7 @@ export class ClaudeAcpAgent {
                                     message.patch.status === "failed" ||
                                     message.patch.status === "killed") {
                                     session.liveBackgroundTasks.delete(message.task_id);
+                                    await this.settleChildSession(message.task_id, message.patch.status);
                                     // Usually first: the notification with its summary follows
                                     // but is not guaranteed, so the terminal ends here.
                                     await endBackgroundTerminal(message.task_id, backgroundExitCode(message.patch.status, message.patch.error));
@@ -4389,7 +4515,11 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                         }
-                        if (session.cancelled) {
+                        // A parent cancel keeps its background subagents running (story
+                        // 065, R3.2): in the RFD form their stream goes on to their child
+                        // sessions even while the parent's cancelled turn drains.
+                        if (session.cancelled &&
+                            !this.childSessions?.childFor(params.sessionId, parentToolUseIdOf(message))) {
                             break;
                         }
                         // Synthetic assistant frames carry the CLI's local-command output.
@@ -4592,7 +4722,11 @@ export class ClaudeAcpAgent {
                             streamedBlocks.length = 0;
                         }
                         else if (message.type === "assistant" &&
-                            !(session.forwardSubagentText || supportsSubagentTranscript(this.clientCapabilities))) {
+                            !(session.forwardSubagentText ||
+                                supportsSubagentTranscript(this.clientCapabilities) ||
+                                // A child session is the subagent's own transcript (story 065):
+                                // its text belongs there, never in the parent's feed.
+                                this.childSessions?.childFor(params.sessionId, message.parent_tool_use_id))) {
                             // Legacy clients don't understand nested transcripts. Keep the
                             // historical behavior for them: subagent text/thinking remains
                             // internal to the tool call instead of leaking into the top-level
@@ -4844,8 +4978,59 @@ export class ClaudeAcpAgent {
         }
     }
     async cancel(params) {
+        if (this.childSessions?.isChild(params.sessionId)) {
+            await this.cancelChildSession(params.sessionId);
+            return;
+        }
         await this.cancelTurns(params, { awaitInterrupt: true });
     }
+    /** Register an ask (permission or question) of `childId`, aborted when that
+     *  child is cancelled; already aborted when it was. No-op for the parent. */
+    openChildAsk(childId) {
+        const controller = new AbortController();
+        if (!childId)
+            return controller;
+        if (this.childSessions.isCancelled(childId)) {
+            controller.abort();
+            return controller;
+        }
+        let asks = this.childAsks.get(childId);
+        if (!asks)
+            this.childAsks.set(childId, (asks = new Set()));
+        asks.add(controller);
+        return controller;
+    }
+    closeChildAsk(childId, controller) {
+        if (childId)
+            this.childAsks.get(childId)?.delete(controller);
+    }
+    /** `session/cancel` naming a child stops that subagent alone: its SDK task,
+     *  never the parent's query, and its open questions are answered denied
+     *  (story 065, R3.1, R3.3). On a failed stop the state stays as reported. */
+    async cancelChildSession(childId) {
+        const parentId = this.childSessions.parentOf(childId);
+        const session = this.sessions[parentId];
+        if (!session) {
+            // The parent is gone, and its query with it: nothing is left to stop.
+            this.logger.log(`[subagents/cancel] outcome=parent_gone sessionId=${logValue(parentId)} childSessionId=${logValue(childId)}`);
+            await this.childSessions.settle(childId, "cancelled");
+            return;
+        }
+        // Join a query recreate, as `cancelTurns` does, so the stop reaches the live query.
+        if (session.queryRecreateInFlight)
+            await session.queryRecreateInFlight;
+        try {
+            await session.query.stopTask(childId);
+        }
+        catch (error) {
+            this.logger.log(`[subagents/cancel] outcome=failed level=warn sessionId=${logValue(parentId)} childSessionId=${logValue(childId)} reason=${logValue(errorMessage(error))}`);
+            throw new Error(`Could not stop subagent ${childId}`, { cause: error });
+        }
+        for (const ask of this.childAsks.get(childId) ?? [])
+            ask.abort();
+        this.childAsks.delete(childId);
+        await this.childSessions.settle(childId, "cancelled");
+    }
     /** Cancel the session's turns and interrupt the SDK query. With
      *  `awaitInterrupt: false` the interrupt is sent, but its reply is not
      *  awaited. `teardownSession` uses that: it closes the query right after, and
@@ -5157,7 +5342,10 @@ export class ClaudeAcpAgent {
         { warn: (message) => this.logger.log(`${message} level=warn`) }, sessionId);
         const taskFeedPublisher = new TaskFeedPublisher(taskFeed, (snapshot) => this.client.sessionUpdate({
             sessionId,
-            update: { sessionUpdate: "session_info_update", _meta: { [TASKS_META_KEY]: snapshot } },
+            update: {
+                sessionUpdate: "session_info_update",
+                _meta: { [TASKS_META_KEY]: this.withChildSessionIds(snapshot) },
+            },
         }), undefined, (error) => this.logger.error(`[tasks/feed] sessionId=${logValue(sessionId)} outcome=send_failed reason=${logValue(errorMessage(error))}`));
         const tailPoller = new TailPoller(taskFeed, taskFeedPublisher, undefined, undefined, (line) => this.logger.log(line), sessionId);
         return { taskFeed, taskFeedPublisher, tailPoller };
@@ -5200,6 +5388,7 @@ export class ClaudeAcpAgent {
         await Promise.all(Object.keys(this.sessions).map((id) => this.teardownSession(id)));
     }
     async closeSession(params) {
+        this.refuseChildSession(params.sessionId, "lifecycle");
         if (!this.sessions[params.sessionId]) {
             throw new Error("Session not found");
         }
@@ -5218,6 +5407,7 @@ export class ClaudeAcpAgent {
         return {};
     }
     async setSessionMode(params) {
+        this.refuseChildSession(params.sessionId, "config");
         // A lazy Thinking recreate may be swapping the session's query right now;
         // join it (mirroring prompt()) so `setPermissionMode` below lands on the
         // replacement query after cutover instead of an about-to-close one — and
@@ -5233,6 +5423,7 @@ export class ClaudeAcpAgent {
         return this.sessionModes.setSessionMode(params);
     }
     async setSessionConfigOption(params) {
+        this.refuseChildSession(params.sessionId, "config");
         const session = this.sessions[params.sessionId];
         if (!session) {
             throw new Error("Session not found");
@@ -5375,8 +5566,99 @@ export class ClaudeAcpAgent {
         await this.applyConfigOptionValue(params.sessionId, session, params.configId, effectiveValue);
         return { configOptions: session.configOptions };
     }
+    /** A resumed parent's children, registered under their transcript ids but
+     *  not announced: a resume replays nothing, and a child the parent
+     *  continues is announced when it runs (story 065, R4.3). */
+    async restoreChildSessions(sessionId) {
+        if (!this.childSessions)
+            return;
+        const session = this.sessions[sessionId];
+        const launches = await readSubagentLaunches(CLAUDE_CONFIG_DIR, sessionId);
+        // Launchers before the subagents they launched, so each nests under its own.
+        const byDepth = [...launches].sort(([, a], [, b]) => a.depth - b.depth);
+        for (const [toolUseId, record] of byDepth) {
+            await this.childSessions.restore(childLaunchOf(sessionId, session, toolUseId, record, {}), {
+                announce: false,
+            });
+        }
+    }
+    /** Replay one child of a loaded parent right after the Agent call that
+     *  launched it: its announcement and prompt on the parent, then its own
+     *  transcript on its session (story 065, R4.1, R4.2). */
+    async replayChildSession(parentId, toolUseId, input, record, launches, replayed) {
+        // Each child once per load: a damaged meta naming a launch inside the
+        // child's own transcript would otherwise recurse without end.
+        if (replayed.has(record.agentId))
+            return;
+        replayed.add(record.agentId);
+        const launch = childLaunchOf(parentId, this.sessions[parentId], toolUseId, record, input);
+        await this.childSessions.restore(launch, { announce: true });
+        if (this.childSessions.parentOf(record.agentId) !== parentId)
+            return;
+        let messages = [];
+        let reason = "empty";
+        try {
+            messages = await getSubagentMessages(parentId, record.agentId);
+        }
+        catch (error) {
+            reason = errorMessage(error);
+        }
+        if (messages.length === 0) {
+            // The SDK answers a missing transcript with []: only the association replays.
+            this.logger.log(`[subagents/replay] outcome=no_transcript level=warn sessionId=${logValue(parentId)} childSessionId=${logValue(record.agentId)} reason=${logValue(reason)}`);
+            return;
+        }
+        const toolUseCache = {};
+        let promptSkipped = false;
+        for (const message of messages) {
+            // @ts-expect-error - untyped in SDK but we handle all of these
+            const role = message.message?.role;
+            // @ts-expect-error - untyped in SDK but we handle all of these
+            let content = message.message?.content;
+            if (role === "user") {
+                // The launch prompt already went out as the parent's session_message.
+                if (!promptSkipped && launch.prompt && userText(content) === launch.prompt) {
+                    promptSkipped = true;
+                    continue;
+                }
+                content = stripLocalCommandMetadata(content);
+                if (content === null)
+                    continue;
+            }
+            for (const notification of toAcpNotifications(
+            // @ts-expect-error - untyped in SDK but we handle all of these
+            content, role, parentId, toolUseCache, this.client, this.logger, {
+                registerHooks: false,
+                clientCapabilities: this.clientCapabilities,
+                cwd: this.sessions[parentId]?.cwd,
+                taskState: this.sessions[parentId]?.taskState,
+                messageId: messageIdForGrouping(message),
+            })) {
+                await this.client.sessionUpdate({ ...notification, sessionId: record.agentId });
+            }
+            // A nested subagent's launch lives in its launcher's transcript.
+            if (role === "assistant") {
+                await this.replayLaunchesIn(parentId, content, launches, replayed);
+            }
+        }
+    }
+    /** Replay the children launched by the Agent calls in `content`. */
+    async replayLaunchesIn(parentId, content, launches, replayed) {
+        for (const block of Array.isArray(content) ? content : []) {
+            const record = block?.type === "tool_use" && typeof block.id === "string"
+                ? launches.get(block.id)
+                : undefined;
+            if (record) {
+                await this.replayChildSession(parentId, block.id, block.input ?? {}, record, launches, replayed);
+            }
+        }
+    }
     async replaySessionHistory(sessionId) {
         const toolUseCache = {};
+        const childLaunches = this.childSessions
+            ? await readSubagentLaunches(CLAUDE_CONFIG_DIR, sessionId)
+            : undefined;
+        const replayedChildren = new Set();
         // getSessionMessages stops at the last compaction boundary; put the history
         // before it back, so a reopened compacted thread scrolls to its first prompt.
         const messages = await withPrecompactHistory(sessionId, await getSessionMessages(sessionId), CLAUDE_CONFIG_DIR);
@@ -5519,6 +5801,9 @@ export class ClaudeAcpAgent {
             })) {
                 await this.client.sessionUpdate(notification);
             }
+            if (childLaunches?.size && message.type === "assistant" && parentToolUseId === null) {
+                await this.replayLaunchesIn(sessionId, content, childLaunches, replayedChildren);
+            }
         }
     }
     async readTextFile(params) {
@@ -5570,21 +5855,44 @@ export class ClaudeAcpAgent {
         // so emit it now if it hasn't been sent yet. The streamed tool_use chunk
         // later refines it with a `tool_call_update` rather than emitting a
         // duplicate (see `emittedToolCalls` in `toAcpNotifications`).
+        // A child's ask is registered before anything awaits, so a cancel of
+        // that child landing meanwhile still answers it (story 065, R3.3).
+        const childId = this.childSessions?.childFor(params.sessionId, parentToolUseId);
+        const childCancel = this.openChildAsk(childId);
         await this.ensureToolCallEmitted(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId, signal);
-        if (signal.aborted)
+        if (signal.aborted) {
+            this.closeChildAsk(childId, childCancel);
             throw new Error("Tool use aborted");
+        }
         // Do not rely on every ACP client settling requestPermission after the
         // cancellation signal. The local race guarantees that Claude's tool call
         // is released even when an older or broken client ignores $/cancel_request.
+        const outgoing = childId ? { ...params, sessionId: childId } : params;
+        const requestSignal = childId ? AbortSignal.any([signal, childCancel.signal]) : signal;
+        if (childId) {
+            if (childCancel.signal.aborted) {
+                this.closeChildAsk(childId, childCancel);
+                throw new ChildSessionCancelled(childId);
+            }
+            await this.childSessions.askOpened(childId);
+        }
         try {
-            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
+            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(outgoing, requestSignal), requestSignal));
         }
         catch (error) {
             if (signal.aborted) {
                 throw new Error("Tool use aborted", { cause: error });
             }
+            if (childCancel.signal.aborted)
+                throw new ChildSessionCancelled(childId);
             throw error;
         }
+        finally {
+            if (childId) {
+                this.closeChildAsk(childId, childCancel);
+                await this.childSessions.askClosed(childId);
+            }
+        }
     }
     /** Emit the `tool_call` a permission request references if it hasn't been sent
      *  yet, so the client has the tool call before being asked to approve it. The
@@ -5685,7 +5993,7 @@ export class ClaudeAcpAgent {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
                 await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal);
-                return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
+                return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal, this.childSessions?.childFor(sessionId, parentToolUseId));
             }
             // Do not auto-allow here based on the session's advertised mode. Claude
             // Code applies bypassPermissions before invoking canUseTool; a request
@@ -5732,11 +6040,20 @@ export class ClaudeAcpAgent {
                     ? undefined
                     : Math.max(0, Math.min(100, Math.round((session.contextUsedTokens / session.contextWindowSize) * 100))),
             });
-            const response = await this.requestPermissionFromClient({
-                ...presentation,
-                options: permissionOptions,
-                sessionId,
-            }, toolName, signal, parentToolUseId);
+            let response;
+            try {
+                response = await this.requestPermissionFromClient({
+                    ...presentation,
+                    options: permissionOptions,
+                    sessionId,
+                }, toolName, signal, parentToolUseId);
+            }
+            catch (error) {
+                if (error instanceof ChildSessionCancelled) {
+                    return { behavior: "deny", message: "The subagent was cancelled." };
+                }
+                throw error;
+            }
             if (signal.aborted)
                 throw new Error("Tool use aborted");
             const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
@@ -5822,17 +6139,31 @@ export class ClaudeAcpAgent {
      * elicitation and return the answers as the tool's `updatedInput`. Called from
      * `canUseTool` since that is where the SDK routes the tool's permission check.
      */
-    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal) {
+    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal, 
+    /** A subagent's question goes out on its child session (story 065, R2.3). */
+    childId) {
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
         }
-        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID);
+        const createRequest = askUserQuestionsToCreateRequest(questions, childId ?? sessionId, toolUseID);
         let response;
+        const childCancel = this.openChildAsk(childId);
+        if (childCancel.signal.aborted) {
+            return { behavior: "deny", message: "The subagent was cancelled." };
+        }
+        const requestSignal = childId ? AbortSignal.any([signal, childCancel.signal]) : signal;
+        if (childId)
+            await this.childSessions?.askOpened(childId);
         try {
-            response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
+            response = await this.withPendingUserInput(sessionId, () => childId
+                ? raceWithAbort(this.client.unstable_createElicitation(createRequest, requestSignal), requestSignal)
+                : this.client.unstable_createElicitation(createRequest, signal));
         }
         catch (error) {
+            if (childCancel.signal.aborted && !signal.aborted) {
+                return { behavior: "deny", message: "The subagent was cancelled." };
+            }
             // A cancellation we requested (signal aborted) settles as an aborted tool
             // use, matching the post-response check below.
             if (signal.aborted) {
@@ -5841,6 +6172,11 @@ export class ClaudeAcpAgent {
             this.logger.error(`Failed to present AskUserQuestion elicitation: ${error}`);
             return { behavior: "deny", message: "Could not present the question to the user." };
         }
+        finally {
+            this.closeChildAsk(childId, childCancel);
+            if (childId)
+                await this.childSessions?.askClosed(childId);
+        }
         if (signal.aborted) {
             throw new Error("Tool use aborted");
         }

package/dist/acp-subagents.d.ts

@@ -0,0 +1,20 @@
+import type { ClientCapabilities } from "@agentclientprotocol/sdk/unstable";
+/**
+ * How a client gets native subagent sessions.
+ *
+ * `rfd`: the subagents RFD (agentclientprotocol/agent-client-protocol#1992,
+ * as revised) — `subagent_update` and `session_message`, which the SDK types.
+ * Ported from upstream `src/acp-subagents.ts` without its `air` form: AIR's
+ * earlier draft of the RFD has no client in this chain (story 065, design.md).
+ */
+export type SubagentForm = "rfd";
+/** The form of native subagent sessions that the client gets, or none. */
+export declare function subagentForm(capabilities?: ClientCapabilities | null): SubagentForm | undefined;
+/**
+ * The schema's `SubagentCapabilities` is an object (`{}` or `{ _meta }`); any
+ * other shape is not a declaration. Zed drops `subagent_update` and
+ * `session_message` from a client that did not advertise it, so a false yes
+ * here loses the subagents entirely.
+ */
+export declare function clientSupportsSubagents(capabilities?: ClientCapabilities | null): boolean;
+//# sourceMappingURL=acp-subagents.d.ts.map

package/dist/acp-subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-subagents.d.ts","sourceRoot":"","sources":["../src/acp-subagents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAE5E;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC;AAEjC,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,YAAY,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,YAAY,GAAG,SAAS,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAGzF"}

package/dist/acp-subagents.js

@@ -0,0 +1,14 @@
+/** The form of native subagent sessions that the client gets, or none. */
+export function subagentForm(capabilities) {
+    return clientSupportsSubagents(capabilities) ? "rfd" : undefined;
+}
+/**
+ * The schema's `SubagentCapabilities` is an object (`{}` or `{ _meta }`); any
+ * other shape is not a declaration. Zed drops `subagent_update` and
+ * `session_message` from a client that did not advertise it, so a false yes
+ * here loses the subagents entirely.
+ */
+export function clientSupportsSubagents(capabilities) {
+    const subagents = capabilities?.subagents;
+    return typeof subagents === "object" && subagents !== null && !Array.isArray(subagents);
+}

package/dist/child-session-history.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Story 065, Task 4.1 — which Agent call launched which subagent, read back
+ * from a session's transcripts so a replayed or restored child keeps the id it
+ * had live (R4.1, R4.3).
+ *
+ * The bundled CLI writes, beside each subagent transcript
+ * `<session>/subagents/agent-<agentId>.jsonl`, a metadata file
+ * `agent-<agentId>.meta.json` whose `toolUseId` names the launching call
+ * (the same layout upstream's `subagent-history.ts` reads). The child id is
+ * the `<agentId>` of the file name — never generated: a launch without
+ * metadata has no known id and is left nested, as before.
+ */
+export type SubagentLaunchRecord = {
+    agentId: string;
+    name?: string;
+    agentType?: string;
+    description?: string;
+    /** `parentAgentId`: the subagent whose agent launched this one (a nested
+     *  subagent, whose launch is in that agent's transcript, not the parent's). */
+    launcherAgentId?: string;
+    /** `spawnDepth`: 1 for a launch by the main thread. */
+    depth: number;
+};
+/** The subagents of `sessionId`, keyed by the tool use id that launched each. */
+export declare function readSubagentLaunches(configDir: string, sessionId: string): Promise<Map<string, SubagentLaunchRecord>>;
+//# sourceMappingURL=child-session-history.d.ts.map

package/dist/child-session-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-session-history.d.ts","sourceRoot":"","sources":["../src/child-session-history.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;mFAC+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAIF,iFAAiF;AACjF,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAoC5C"}