@agentclientprotocol/claude-agent-acp 0.91.1-preview.3 → 0.91.1-preview.5

package/dist/native-subagents.js

@@ -15,6 +15,7 @@ export class NativeSubagentRuntime {
     publish;
     logger;
     lineage;
+    launchedAgent;
     enabled;
     /** The form of the child sessions; see {@link SubagentForm}. */
     form;
@@ -31,23 +32,37 @@ export class NativeSubagentRuntime {
      */
     childByToolCall = new Map();
     taskFinishPromises = new Map();
-    /** The RFD form: the session that made each SendMessage call. */
+    /** The session that made each SendMessage call. */
     senderByToolUse = new Map();
     generationByTaskId = new Map();
     pending = new Map();
     pendingCount = 0;
+    /** The AIR form: agents being restored from the history, by agent id. */
+    agentRestores = new Map();
+    /** The AIR form: launch ids being resolved to an agent, by launch id. */
+    launchRestores = new Map();
+    /** The AIR form: launch ids that the history has no restorable agent for. */
+    unresolvedLaunches = new Set();
+    /** The AIR form: agents that the history could not place, so it is read once. */
+    unrestorableAgents = new Set();
+    /** The latest generation number given to a restored agent. */
+    lastRestoredGeneration = 0;
+    /** Bumped when the restore state is dropped; a restore that began before it is void. */
+    restoreEpoch = 0;
     /** The RFD form: how many times the parent was cancelled (see {@link awaitingUser}). */
     parentCancels = 0;
     /**
      * `form` is undefined for a client without native subagent sessions. The RFD
-     * form restores an agent from before a load or resume with `lineage`.
+     * form restores an agent from before a load or resume with `lineage`. The AIR
+     * form does too, and `launchedAgent` finds the agent that a launch call made.
      */
-    constructor(form, rootSessionId, session, publish, logger, lineage) {
+    constructor(form, rootSessionId, session, publish, logger, lineage, launchedAgent) {
         this.rootSessionId = rootSessionId;
         this.session = session;
         this.publish = publish;
         this.logger = logger;
         this.lineage = lineage;
+        this.launchedAgent = launchedAgent;
         this.form = form;
         this.enabled = form !== undefined;
         this.children = session.nativeSubagentsByTaskId ??= new Map();
@@ -61,7 +76,7 @@ export class NativeSubagentRuntime {
     }
     async route(notification, deliver, forcedSessionId) {
         const routed = await this.routeUpdate(notification, deliver, forcedSessionId);
-        if (routed && this.form === "rfd")
+        if (routed)
             this.rememberSendMessage(routed);
         return routed;
     }
@@ -137,7 +152,13 @@ export class NativeSubagentRuntime {
         if (this.enabled && claudeMeta?.parentToolUseId) {
             const child = this.childByParentToolUse.get(claudeMeta.parentToolUseId);
             if (!child || !child.announced) {
-                this.buffer(claudeMeta.parentToolUseId, notification);
+                const launchId = claudeMeta.parentToolUseId;
+                this.buffer(launchId, notification);
+                // An id that this process never saw is the launch call of an agent
+                // from before a load or resume; a new Agent call is known by now.
+                if (!child && this.form === "air" && this.isUnseenLaunch(launchId)) {
+                    await this.restoreLaunch(launchId, deliver);
+                }
                 return null;
             }
             return this.toChild(child, notification, toolCallId);
@@ -157,6 +178,22 @@ export class NativeSubagentRuntime {
             await this.resumeChild(known, task.taskId, promptText(task.prompt), task.toolUseId ?? undefined, deliver);
             return;
         }
+        // The SDK starts an agent from before a restart under the id of the
+        // SendMessage call that resumed it, as in the RFD form (see `restore`).
+        // Its output comes under the id of the call that launched it.
+        if (this.form === "air" &&
+            task.subagentType &&
+            task.toolUseId &&
+            this.senderByToolUse.has(task.toolUseId) &&
+            !this.children.has(task.taskId)) {
+            await this.restoreAgent(task.taskId, deliver, promptText(task.prompt));
+            const restored = this.children.get(task.taskId);
+            if (restored) {
+                this.taskByToolUse.set(task.toolUseId, task.taskId);
+                this.childByParentToolUse.set(task.toolUseId, restored);
+                return;
+            }
+        }
         if (!task.subagentType) {
             if (task.toolUseId) {
                 this.takePending(task.toolUseId);
@@ -193,13 +230,19 @@ export class NativeSubagentRuntime {
      * 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.
+     *
+     * In the AIR form, an agent that the runtime does not know is restored from
+     * the session's history (see {@link restoreAgent}).
      */
     async taskResumed(taskId, deliver, prompt) {
         if (!this.enabled)
             return;
         const previous = this.children.get(taskId);
-        if (!previous)
+        if (!previous) {
+            if (this.form === "air")
+                await this.restoreAgent(taskId, deliver, prompt);
             return;
+        }
         const finishing = this.taskFinishPromises.get(taskId) ?? previous.terminalPromise;
         if (finishing)
             await finishing.catch(() => { });
@@ -350,6 +393,7 @@ export class NativeSubagentRuntime {
             this.identityByToolUse.clear();
             this.controlByToolUse.clear();
             this.parentByToolUse.clear();
+            this.forgetRestores();
         }
         if (errors.length === 1)
             throw errors[0];
@@ -496,6 +540,105 @@ export class NativeSubagentRuntime {
         }
         return this.children.get(agentId);
     }
+    /**
+     * The AIR form: whether no call of this process made `launchId`. A new Agent
+     * call has a control update before its `task_started`, and a launch that was
+     * restored or looked up is registered or remembered.
+     */
+    isUnseenLaunch(launchId) {
+        return (!!this.launchedAgent && !this.unresolvedLaunches.has(launchId) && this.isUnseenCall(launchId));
+    }
+    /** Whether this runtime has no record of the tool call `toolUseId`. */
+    isUnseenCall(toolUseId) {
+        return (!this.taskByToolUse.has(toolUseId) &&
+            !this.childByParentToolUse.has(toolUseId) &&
+            !this.controlByToolUse.has(toolUseId) &&
+            !this.parentByToolUse.has(toolUseId) &&
+            !this.identityByToolUse.has(toolUseId));
+    }
+    /**
+     * The AIR form: restores the agent that the call `launchId` launched, once.
+     * Concurrent callers wait for the same lookup. Without an agent, the updates
+     * buffered under `launchId` stay buffered and `launchId` is not looked up again.
+     */
+    restoreLaunch(launchId, deliver) {
+        const existing = this.launchRestores.get(launchId);
+        if (existing)
+            return existing;
+        const epoch = this.restoreEpoch;
+        const restoring = (async () => {
+            const agentId = await this.launchedAgent?.(launchId).catch((error) => {
+                this.logger.log(`Session ${this.rootSessionId}: failed to read the history of launch ${launchId}: ${error}`);
+                return undefined;
+            });
+            if (epoch !== this.restoreEpoch)
+                return;
+            if (agentId)
+                await this.restoreAgent(agentId, deliver);
+            if (epoch !== this.restoreEpoch)
+                return;
+            const child = this.childByParentToolUse.get(launchId);
+            if (!child) {
+                this.unresolvedLaunches.add(launchId);
+                return;
+            }
+            // Updates that arrived while the generation was announced.
+            if (child.announced)
+                for (const pending of this.takePending(launchId))
+                    await deliver(pending);
+        })().finally(() => {
+            if (this.launchRestores.get(launchId) === restoring)
+                this.launchRestores.delete(launchId);
+        });
+        this.launchRestores.set(launchId, restoring);
+        return restoring;
+    }
+    /**
+     * The AIR form: opens a generation for the agent `agentId` that the runtime
+     * does not know, because it ran before the session was loaded or resumed.
+     * The session's subagent history (see {@link SubagentLineage}) gives the
+     * call that launched it: Claude Code sends the resumed run's messages under
+     * that call's id, so it is the generation's parent tool use, and the updates
+     * buffered under it are delivered. The parent is the agent that made the call
+     * if it is live, else the root. An agent that the history cannot place is
+     * not restored. Concurrent signals for one agent open one generation.
+     */
+    restoreAgent(agentId, deliver, prompt) {
+        if (!this.lineage || this.children.has(agentId) || this.unrestorableAgents.has(agentId)) {
+            return Promise.resolve();
+        }
+        const existing = this.agentRestores.get(agentId);
+        if (existing)
+            return existing;
+        const lineage = this.lineage;
+        const epoch = this.restoreEpoch;
+        const restoring = (async () => {
+            const entries = await lineage(agentId).catch((error) => {
+                this.logger.log(`Session ${this.rootSessionId}: failed to read the history of subagent ${agentId}: ${error}`);
+                return [];
+            });
+            if (epoch !== this.restoreEpoch || this.children.has(agentId))
+                return;
+            const entry = entries.at(-1);
+            if (!entry || entry.agentId !== agentId) {
+                this.unrestorableAgents.add(agentId);
+                return;
+            }
+            const parent = entry.parentAgentId ? this.children.get(entry.parentAgentId) : undefined;
+            await this.openGeneration(agentId, undefined, {
+                parentSessionId: parent && this.isLiveSession(parent.sessionId) ? parent.sessionId : this.rootSessionId,
+                parentToolUseId: entry.launchId,
+                name: subagentDisplayName(entry.name, entry.description, entry.agentType, agentId),
+                task: subagentDescription(undefined, entry.description),
+                ...promptField(promptText(prompt)),
+            }, true, deliver, true);
+        })().finally(() => {
+            if (this.agentRestores.get(agentId) === restoring)
+                this.agentRestores.delete(agentId);
+        });
+        this.agentRestores.set(agentId, restoring);
+        return restoring;
+    }
     /**
      * 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
@@ -668,6 +811,15 @@ export class NativeSubagentRuntime {
         this.generationByTaskId.clear();
         this.pending.clear();
         this.pendingCount = 0;
+        this.forgetRestores();
+    }
+    /** Lets a later resume signal restore an agent again, and look up a launch again. */
+    forgetRestores() {
+        this.agentRestores.clear();
+        this.launchRestores.clear();
+        this.unresolvedLaunches.clear();
+        this.unrestorableAgents.clear();
+        this.restoreEpoch++;
     }
     takePending(parentToolUseId) {
         const updates = this.pending.get(parentToolUseId) ?? [];
@@ -716,9 +868,9 @@ export class NativeSubagentRuntime {
      * parent tool call. With `announce`, it publishes `subagent_spawned` and
      * delivers the updates that waited for the child.
      */
-    async openGeneration(taskId, previous, fields, announce, deliver) {
+    async openGeneration(taskId, previous, fields, announce, deliver, restored = false) {
         const child = {
-            sessionId: this.nextChildSessionId(taskId, previous),
+            sessionId: this.nextChildSessionId(taskId, previous, restored),
             ...fields,
         };
         const toolUseId = child.parentToolUseId;
@@ -743,8 +895,21 @@ export class NativeSubagentRuntime {
      * `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.
+     *
+     * An agent restored from the history (`restored`) is not on its first
+     * generation: before the restart the client already stored ids such as
+     * `taskId` and `taskId:generation:2`. Its generation is the current time in
+     * milliseconds, so it is `taskId:generation:1760000000000`, and each later
+     * resume in this process adds one.
      */
-    nextChildSessionId(taskId, previous) {
+    nextChildSessionId(taskId, previous, restored = false) {
+        if (restored) {
+            // A clear() and a new restore within one millisecond must not repeat an id.
+            const generation = Math.max(Date.now(), this.lastRestoredGeneration + 1);
+            this.lastRestoredGeneration = generation;
+            this.generationByTaskId.set(taskId, generation);
+            return `${taskId}:generation:${generation}`;
+        }
         if (!previous) {
             this.generationByTaskId.set(taskId, 1);
             return taskId;

package/dist/subagent-history.d.ts

@@ -34,6 +34,11 @@ export interface SubagentHistory {
  * The ids are empty for a session without a local transcript.
  */
 export declare function subagentHistory(sessionId: string): Promise<SubagentHistory>;
+/**
+ * The agent that the Agent or Task call `launchId` launched, from the subagent
+ * history of the session `sessionId`.
+ */
+export declare function subagentLaunchedBy(sessionId: string, launchId: string): Promise<string | undefined>;
 /**
  * The agent `agentId` and its ancestors, root first, from the subagent history
  * of the session `sessionId`. The runtime restores an agent from it when Claude

package/dist/subagent-history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-history.d.ts","sourceRoot":"","sources":["../src/subagent-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAA+B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG7F,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAwCjF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IAAE,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAAE,GAC1C,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqD/B;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAW5D;AAQD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE;IAAE,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAAE,GAC1C,OAAO,CAAC,cAAc,EAAE,CAAC,CAW3B"}
+{"version":3,"file":"subagent-history.d.ts","sourceRoot":"","sources":["../src/subagent-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,gCAAgC,CAAC;AAKxC,OAAO,EAA+B,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG7F,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAwCjF;AAOD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IAAE,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAAE,GAC1C,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAmD/B;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAW5D;AAkDD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE;IAAE,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAAE,GAC1C,OAAO,CAAC,cAAc,EAAE,CAAC,CAW3B"}

package/dist/subagent-history.js

@@ -1,6 +1,8 @@
-import { getSessionInfo, getSessionMessages, getSubagentMessages, } from "@anthropic-ai/claude-agent-sdk";
+import { getSessionInfo, getSubagentMessages, } from "@anthropic-ai/claude-agent-sdk";
+import { createReadStream } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import readline from "node:readline";
 import { isNativeSubagentControlTool } from "./native-subagents.js";
 import { findTranscript } from "./resumed-session.js";
 /**
@@ -16,7 +18,7 @@ export async function subagentHistory(sessionId) {
     const transcript = await findTranscript(sessionId);
     if (!transcript)
         return { agents };
-    const directory = path.join(path.dirname(transcript), sessionId, "subagents");
+    const directory = subagentsDirectory(transcript, sessionId);
     let names;
     try {
         names = await readdir(directory);
@@ -53,6 +55,17 @@ export async function subagentHistory(sessionId) {
     const dir = (await getSessionInfo(sessionId).catch(() => undefined))?.cwd;
     return dir ? { agents, dir } : { agents };
 }
+/** The folder of the subagent transcripts, next to the session transcript `transcript`. */
+function subagentsDirectory(transcript, sessionId) {
+    return path.join(path.dirname(transcript), sessionId, "subagents");
+}
+/**
+ * The agent that the Agent or Task call `launchId` launched, from the subagent
+ * history of the session `sessionId`.
+ */
+export async function subagentLaunchedBy(sessionId, launchId) {
+    return (await subagentHistory(sessionId)).agents.get(launchId)?.agentId;
+}
 /**
  * The agent `agentId` and its ancestors, root first, from the subagent history
  * of the session `sessionId`. The runtime restores an agent from it when Claude
@@ -72,11 +85,12 @@ export async function subagentLineage(sessionId, agentId, logger) {
     }
     if (!launchOf.has(agentId))
         return [];
-    // Without the project directory, as the replay reads it (`readResumedSession`).
-    const rootLaunches = new Set(launchIdsIn(await getSessionMessages(sessionId).catch((error) => {
-        logger.error(`Failed to read the transcript of session ${sessionId}:`, error);
+    // The SDK's readers return only the active chain, which starts after the
+    // last compaction, so the launch calls come from the transcript files.
+    const transcript = await findTranscript(sessionId);
+    if (!transcript)
         return [];
-    })));
+    const rootLaunches = await readLaunchIdsFromTranscript(transcript, null, logger);
     const agentLaunches = new Map();
     /** The agent whose transcript has the launch `launchId`, `null` for the root's. */
     const launcherOf = async (launchId) => {
@@ -85,7 +99,7 @@ export async function subagentLineage(sessionId, agentId, logger) {
         for (const candidate of launchOf.keys()) {
             let launches = agentLaunches.get(candidate);
             if (!launches) {
-                launches = new Set(launchIdsIn(await readSubagentMessages(sessionId, candidate, history, logger)));
+                launches = await readLaunchIdsFromTranscript(path.join(subagentsDirectory(transcript, sessionId), `agent-${candidate}.jsonl`), candidate, logger);
                 agentLaunches.set(candidate, launches);
             }
             if (launches.has(launchId))
@@ -127,8 +141,47 @@ export function subagentLaunchIds(content) {
         ? [block.id]
         : []);
 }
-function launchIdsIn(messages) {
-    return messages.flatMap((message) => subagentLaunchIds(message.message?.content));
+/**
+ * The ids of the launch calls in the transcript `file`, every record of it,
+ * including those before a compaction. `owner` is the agent the transcript
+ * belongs to, null for the session's. The session's transcript can hold
+ * sidechain records, which are an agent's, not the root's; an agent's
+ * transcript keeps only the records of that agent. A file that cannot be read
+ * has no launches, so the agent is not placed under the root.
+ */
+async function readLaunchIdsFromTranscript(file, owner, logger) {
+    const launches = new Set();
+    const stream = createReadStream(file, { encoding: "utf8" });
+    try {
+        for await (const line of readline.createInterface({ input: stream, crlfDelay: Infinity })) {
+            if (!line.includes('"tool_use"'))
+                continue;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (record?.type !== "assistant")
+                continue;
+            if (owner === null
+                ? record.isSidechain === true
+                : record.agentId !== undefined && record.agentId !== owner) {
+                continue;
+            }
+            for (const id of subagentLaunchIds(record.message?.content))
+                launches.add(id);
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to read the transcript ${file}:`, error);
+        return new Set();
+    }
+    finally {
+        stream.destroy();
+    }
+    return launches;
 }
 /**
  * The transcript of the subagent `agentId` of a session, or an empty list

package/dist/v2/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAoB9E;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CA2Eb"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAoB9E;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CAkFb"}

package/dist/v2/agent.js

@@ -50,6 +50,13 @@ export function v2AgentApp(logger, onAgent) {
         const response = restore.method === "resume"
             ? await agent.resumeSession(restore.request)
             : await client.replaying(params.sessionId, () => agent.loadSession(restore.request));
+        // v2 requires a snapshot of the foreground state after the replay and
+        // before the response, also without a replay: a resumed live session can
+        // be running a turn, or waiting on a permission request.
+        void client.send({
+            sessionId: params.sessionId,
+            update: stateSnapshot(agent.foregroundState(params.sessionId)),
+        });
         return {
             ...v2ResumeSessionResponse(response),
             ...(await setupCommands(agent, params.sessionId, logger)),
@@ -80,6 +87,14 @@ export function v2AgentApp(logger, onAgent) {
     }))
         .onNotification(v2.methods.agent.session.cancel, ({ params }) => agent.cancel(params));
 }
+/** The `state_update` that reports `state` as the current foreground state. */
+function stateSnapshot(state) {
+    if (state === "idle")
+        return { sessionUpdate: "state_update", state: "idle" };
+    if (state === "running")
+        return { sessionUpdate: "state_update", state: "running" };
+    return { sessionUpdate: "state_update", state: "requires_action" };
+}
 /**
  * The `availableCommands` of a setup response, so a client can show the
  * session's commands without waiting for an update. The agent sends a v1
@@ -113,6 +128,13 @@ class V2ClientConnection {
     replays = new Map();
     /** The session whose replay announced each replaying subagent. */
     replayRoots = new Map();
+    /**
+     * The last work state that a replay reported for each subagent, as the
+     * `state_update` of the child's own stream. It goes out once the replay
+     * ends: v2 forbids replaying a child's past `running` and `idle` as current
+     * activity.
+     */
+    replayedChildStates = new Map();
     /** The display terminals of the commands that the agent runs. */
     terminals = new V2Terminals();
     /** The `_meta` that the client stores for each tool call. */
@@ -128,19 +150,28 @@ class V2ClientConnection {
      * replayed message, and chunks append, so before the first replayed chunk of
      * each message the client gets the message with no content, which clears it,
      * as v2 requires of a message replayed as chunks.
+     *
+     * Each replayed subagent gets one `state_update` on its own stream, with its
+     * last state, after the replay.
      */
     async replaying(sessionId, restore) {
         this.replays.set(sessionId, new Set());
+        const children = () => [...this.replayRoots].filter(([, root]) => root === sessionId).map(([child]) => child);
         try {
-            return await restore();
+            const result = await restore();
+            for (const child of children()) {
+                const state = this.replayedChildStates.get(child);
+                if (state)
+                    void this.send(state);
+            }
+            return result;
         }
         finally {
             this.replays.delete(sessionId);
-            for (const [child, root] of this.replayRoots) {
-                if (root !== sessionId)
-                    continue;
+            for (const child of children()) {
                 this.replays.delete(child);
                 this.replayRoots.delete(child);
+                this.replayedChildStates.delete(child);
             }
         }
     }
@@ -178,8 +209,13 @@ class V2ClientConnection {
             return clear ? [clear, v2Update] : [v2Update];
         });
         // A subagent's work state also goes to the child's own stream, after the
-        // parent's copy.
-        const childState = v2ChildStateUpdate(update);
+        // parent's copy. During a replay, only its last state goes, after the
+        // replay (see `replayedChildStates`).
+        let childState = v2ChildStateUpdate(update);
+        if (childState && this.replays.has(notification.sessionId)) {
+            this.replayedChildStates.set(childState.sessionId, childState);
+            childState = undefined;
+        }
         // Every update goes to the connection before any is awaited, so an update
         // that another call sends meanwhile cannot come between them.
         await Promise.all([
@@ -190,7 +226,8 @@ class V2ClientConnection {
     /**
      * The v2 updates of a v1 update: for a tool call report, the updates of its
      * terminal first (see {@link V2Terminals}), then the report itself, with the
-     * `_meta` that the client stores (see {@link V2ToolCallMeta}).
+     * `_meta` keys that it changes (see {@link V2ToolCallMeta}), and during a
+     * replay the `_meta` of a tool call that the report cleared.
      */
     v2Updates(sessionId, update) {
         if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
@@ -201,8 +238,16 @@ class V2ClientConnection {
         if (!report)
             return terminal;
         const starts = report.sessionUpdate === "tool_call";
-        const reportUpdate = v2SessionUpdate(this.toolCallMeta.apply(sessionId, report, starts));
-        return [...terminal, ...(reportUpdate ? [reportUpdate] : [])];
+        const [reported, metaPatch] = this.toolCallMeta.apply(sessionId, report, starts, this.replays.has(sessionId));
+        const reportUpdate = v2SessionUpdate(reported);
+        const metaUpdate = metaPatch
+            ? v2SessionUpdate({ sessionUpdate: "tool_call_update", ...metaPatch })
+            : undefined;
+        return [
+            ...terminal,
+            ...(reportUpdate ? [reportUpdate] : []),
+            ...(metaUpdate ? [metaUpdate] : []),
+        ];
     }
     /**
      * The update that clears the message of a replayed chunk, when it is the

package/dist/v2/initialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initialize.d.ts","sourceRoot":"","sources":["../../src/v2/initialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAE/D,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,GAAG,iBAAiB,CAmCpF;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,EAAE,CAAC,kBAAkB,CAuBxF"}
+{"version":3,"file":"initialize.d.ts","sourceRoot":"","sources":["../../src/v2/initialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAG/D,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,GAAG,iBAAiB,CAmCpF;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,EAAE,CAAC,kBAAkB,CAuBxF"}

package/dist/v2/initialize.js

@@ -9,6 +9,7 @@
  */
 import { PROTOCOL_VERSION as V1_PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
 import * as v2 from "@agentclientprotocol/sdk/experimental/v2";
+import { SYSTEM_PROMPT_CAPABILITY } from "../client-system-prompt.js";
 /** The v1 `initialize` request that a v2 client means. */
 export function v1InitializeRequest(request) {
     const capabilities = request.capabilities;
@@ -91,6 +92,7 @@ export function v2InitializeResponse(response) {
  * - The prompt content and MCP transports that the agent's v1 `initialize`
  *   lists: images, embedded context, and HTTP servers. Stdio servers are in the
  *   v1 baseline; v2 has no SSE transport.
+ * - `systemPrompt`, in `append` and `override` mode.
  */
 const V2_SESSION_CAPABILITIES = {
     prompt: { image: {}, embeddedContext: {} },
@@ -98,6 +100,7 @@ const V2_SESSION_CAPABILITIES = {
     delete: {},
     fork: {},
     additionalDirectories: {},
+    systemPrompt: SYSTEM_PROMPT_CAPABILITY,
 };
 /** v2 names the id of a method `methodId`, requires `type`, and lists `env` as name and value pairs. */
 function v2AuthMethod(method) {

package/dist/v2/prompt.d.ts

@@ -4,7 +4,7 @@
  * v2 answers the prompt once Claude Code takes it in, with the id of the user
  * message it became, and reports the rest of the turn as `state_update`s.
  */
-import { type PromptRequest } from "@agentclientprotocol/sdk";
+import { type ContentBlock, type PromptRequest } from "@agentclientprotocol/sdk";
 import * as v2 from "@agentclientprotocol/sdk/experimental/v2";
 import type { ClaudeAcpAgent } from "../acp-agent.js";
 import type { ForegroundEvents } from "../turn-events.js";
@@ -50,4 +50,5 @@ export declare function v2Foreground(send: (update: v2.SessionUpdate) => void):
  * advertised, so such a block is rejected rather than silently dropped.
  */
 export declare function v1PromptRequest({ prompt, ...request }: v2.PromptRequest): PromptRequest;
+export declare function v1ContentBlock(block: v2.ContentBlock): ContentBlock;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/v2/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/v2/prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAIL,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAuC,MAAM,mBAAmB,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,EAAE,CAAC,aAAa,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,GACvC,OAAO,CAAC,EAAE,CAAC,cAAc,CAAC,CAiC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,GAAG,gBAAgB,CAoBvF;AAgCD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,aAAa,GAAG,aAAa,CAEvF"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/v2/prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAuC,MAAM,mBAAmB,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,EAAE,CAAC,aAAa,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,GACvC,OAAO,CAAC,EAAE,CAAC,cAAc,CAAC,CAiC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,KAAK,IAAI,GAAG,gBAAgB,CAoBvF;AAgCD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,aAAa,GAAG,aAAa,CAEvF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,GAAG,YAAY,CAenE"}

package/dist/v2/prompt.js

@@ -129,7 +129,7 @@ function idle({ stopReason, usage, _meta }) {
 export function v1PromptRequest({ prompt, ...request }) {
     return { ...request, prompt: prompt.map(v1ContentBlock) };
 }
-function v1ContentBlock(block) {
+export function v1ContentBlock(block) {
     if (v2.ContentBlock.isText(block) ||
         v2.ContentBlock.isImage(block) ||
         v2.ContentBlock.isAudio(block) ||

package/dist/v2/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/v2/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EAGxB,KAAK,6BAA6B,EACnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,EAAE,CAAC,iBAAiB,GAAG,iBAAiB,CAInF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,EAAE,CAAC,oBAAoB,GAE7B;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAkBlD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,EAAE,CAAC,kBAAkB,GAAG,kBAAkB,CAGtF;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,EAAE,CAAC,kBAAkB,CAExF;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,EAAE,CAAC,qBAAqB,CAKjG;AAED,uEAAuE;AACvE,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,EAAE,CAAC,6BAA6B,GACvC,6BAA6B,CAgB/B;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE,CAQxF;AAWD,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAKvF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/v2/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAEvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EAGxB,KAAK,6BAA6B,EAEnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAG/D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,EAAE,CAAC,iBAAiB,GAAG,iBAAiB,CAQnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,EAAE,CAAC,oBAAoB,GAE7B;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAmBlD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,EAAE,CAAC,kBAAkB,GAAG,kBAAkB,CAOtF;AAaD,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,EAAE,CAAC,kBAAkB,CAExF;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,EAAE,CAAC,qBAAqB,CAKjG;AAED,uEAAuE;AACvE,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,EAAE,CAAC,6BAA6B,GACvC,6BAA6B,CAgB/B;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE,CAQxF;AAWD,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAKvF"}

package/dist/v2/session.js

@@ -5,10 +5,15 @@
  */
 import { RequestError, } from "@agentclientprotocol/sdk";
 import * as v2 from "@agentclientprotocol/sdk/experimental/v2";
+import { v1ContentBlock } from "./prompt.js";
 export function v1NewSessionRequest(params) {
-    const { mcpServers, ...request } = params;
+    const { mcpServers, systemPrompt, ...request } = params;
     // v1 requires the list; v2 treats an omitted list as an empty one.
-    return { ...request, mcpServers: (mcpServers ?? []).map(v1McpServer) };
+    return {
+        ...request,
+        mcpServers: (mcpServers ?? []).map(v1McpServer),
+        ...v1SystemPromptField(systemPrompt),
+    };
 }
 /**
  * The v1 request that a v2 `session/resume` means.
@@ -20,7 +25,8 @@ export function v1NewSessionRequest(params) {
  * starts elsewhere is rejected.
  */
 export function v1RestoreSessionRequest(params) {
-    const { replayFrom, mcpServers, ...request } = params;
+    const { replayFrom, mcpServers, systemPrompt, ...rest } = params;
+    const request = { ...rest, ...v1SystemPromptField(systemPrompt) };
     if (replayFrom == null) {
         return {
             method: "resume",
@@ -40,8 +46,21 @@ export function v1RestoreSessionRequest(params) {
  * returns a session that the client can prompt, with its config options.
  */
 export function v1ForkSessionRequest(params) {
-    const { mcpServers, ...request } = params;
-    return { ...request, ...(mcpServers ? { mcpServers: mcpServers.map(v1McpServer) } : {}) };
+    const { mcpServers, systemPrompt, ...request } = params;
+    return {
+        ...request,
+        ...(mcpServers ? { mcpServers: mcpServers.map(v1McpServer) } : {}),
+        ...v1SystemPromptField(systemPrompt),
+    };
+}
+/**
+ * The v1 `systemPrompt`. Its content converts like prompt content: a v2
+ * annotation audience can be any string, and v1 takes only `user` or `assistant`.
+ */
+function v1SystemPromptField(systemPrompt) {
+    if (systemPrompt == null)
+        return {};
+    return { systemPrompt: { ...systemPrompt, content: systemPrompt.content.map(v1ContentBlock) } };
 }
 /** v2 drops `modes`: the session mode is the `mode` config option, which the agent always lists. */
 export function v2NewSessionResponse(response) {