@agentclientprotocol/claude-agent-acp 0.81.2 → 0.81.3-preview.2

package/dist/tool-calls/changed-meta-filter.js

@@ -0,0 +1,102 @@
+/** The `_meta` namespaces whose keys a client merges one by one. */
+const MERGED_NAMESPACES = ["claudeCode"];
+/** The top-level `_meta` flags that stay the same for a tool call. */
+const FLAGS = ["is_mcp_tool_call", "terminal_info"];
+/** The number of tool calls whose `_meta` the filter remembers. */
+const TOOL_CALL_LIMIT = 2048;
+/**
+ * Removes the `_meta` keys of a `tool_call_update` that an earlier report of
+ * the same tool call already sent with the same value.
+ *
+ * Only an AIR client gets the filtered updates, because AIR merges these
+ * `_meta` keys. ACP does not define a merge for `_meta` keys, so another
+ * client gets every key on every update.
+ *
+ * It runs on the final notification, after the native subagent routing,
+ * because the routing reads `claudeCode.toolName` and
+ * `claudeCode.parentToolUseId` on every update. It compares the keys of
+ * `claudeCode`, of `jetbrains.air`, and the flags `is_mcp_tool_call` and
+ * `terminal_info`. It never compares `terminal_output`,
+ * `terminal_output_delta`, `terminal_exit`, or `mcp_output_delta`: a client
+ * appends their data. An update with nothing left is dropped.
+ */
+export class ChangedMetaFilter {
+    sent = new Map();
+    /** Returns the update without the unchanged keys, or null when nothing is left. */
+    apply(update) {
+        if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+            return update;
+        }
+        let held = this.sent.get(update.toolCallId);
+        if (update.sessionUpdate === "tool_call" || !held) {
+            held = new Map();
+            this.remember(update.toolCallId, held);
+            recordAndStrip(held, update._meta, false);
+            return update;
+        }
+        this.remember(update.toolCallId, held);
+        if (!update._meta)
+            return update;
+        const meta = structuredClone(update._meta);
+        recordAndStrip(held, meta, true);
+        const filtered = { ...update, _meta: meta };
+        if (Object.keys(meta).length === 0)
+            delete filtered._meta;
+        const carriesSomething = Object.keys(filtered).some((key) => key !== "sessionUpdate" && key !== "toolCallId");
+        return carriesSomething ? filtered : null;
+    }
+    /** Stores the entry as the most recent one, and forgets the oldest one past the limit. */
+    remember(toolCallId, held) {
+        this.sent.delete(toolCallId);
+        this.sent.set(toolCallId, held);
+        if (this.sent.size > TOOL_CALL_LIMIT) {
+            const oldest = this.sent.keys().next().value;
+            if (oldest !== undefined)
+                this.sent.delete(oldest);
+        }
+    }
+}
+/** Records the compared keys of `meta`. With `strip`, deletes the unchanged ones. */
+function recordAndStrip(held, meta, strip) {
+    if (!meta)
+        return;
+    const keep = (key, value) => {
+        const json = JSON.stringify(value);
+        if (strip && held.get(key) === json)
+            return false;
+        held.set(key, json);
+        return true;
+    };
+    const mergeKeys = (prefix, values) => {
+        for (const [key, value] of Object.entries(values)) {
+            if (!keep(prefix + key, value))
+                delete values[key];
+        }
+    };
+    for (const namespace of MERGED_NAMESPACES) {
+        const values = asRecord(meta[namespace]);
+        if (!values)
+            continue;
+        mergeKeys(`${namespace}.`, values);
+        if (Object.keys(values).length === 0)
+            delete meta[namespace];
+    }
+    const jetbrains = asRecord(meta.jetbrains);
+    const air = asRecord(jetbrains?.air);
+    if (jetbrains && air) {
+        mergeKeys("jetbrains.air.", air);
+        if (Object.keys(air).length === 0)
+            delete jetbrains.air;
+        if (Object.keys(jetbrains).length === 0)
+            delete meta.jetbrains;
+    }
+    for (const flag of FLAGS) {
+        if (meta[flag] !== undefined && !keep(flag, meta[flag]))
+            delete meta[flag];
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/tool-calls/client-capabilities.d.ts

@@ -0,0 +1,51 @@
+import type { ClientCapabilities as AcpClientCapabilities } from "@agentclientprotocol/sdk";
+/**
+ * The client choices that decide the shape of a tool call report.
+ *
+ * The agent reads them once from `initialize.clientCapabilities`. The public
+ * `toAcpNotifications` functions take the ACP capabilities and read them on
+ * each call. The {@link AcpToolCallRenderer} reads nothing else, so one object
+ * holds every capability choice of a tool call report.
+ */
+export declare class ClientCapabilities {
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    readonly terminalOutput: boolean;
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    readonly terminalOutputDelta: boolean;
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    readonly diffPatch: boolean;
+    /** The capabilities that only JetBrains AIR declares. */
+    readonly air: AirCapabilities;
+    constructor(
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    terminalOutput?: boolean, 
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    terminalOutputDelta?: boolean, 
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    diffPatch?: boolean, 
+    /** The capabilities that only JetBrains AIR declares. */
+    air?: AirCapabilities);
+    static from(capabilities: AcpClientCapabilities | null | undefined): ClientCapabilities;
+}
+/** The capabilities of JetBrains AIR, read from `_meta.jetbrains.air`. */
+export interface AirCapabilities {
+    /**
+     * The client declared `_meta.jetbrains.air`. Only then does a report follow
+     * the tool call contract of `docs/air-extensions.md`. Every other client
+     * gets the fields of the upstream adapter, and only the unchanged fields of
+     * an update are left out.
+     */
+    readonly client: boolean;
+    /**
+     * AIR renders `rawInput` itself. A tool call report for AIR then carries no
+     * display copy of the input in `content`.
+     */
+    readonly rawInputRendering: boolean;
+    /**
+     * AIR reads the plan of an ExitPlanMode from the file that
+     * `rawInput.planFilePath` names. A report then carries the path and not the
+     * plan text, when the plan file exists.
+     */
+    readonly planFile: boolean;
+}
+//# sourceMappingURL=client-capabilities.d.ts.map

package/dist/tool-calls/client-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-capabilities.d.ts","sourceRoot":"","sources":["../../src/tool-calls/client-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,IAAI,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAS5F;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAE3B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,OAAO;IACrC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,eAAe;;IAP7B,wGAAwG;IAC/F,cAAc,GAAE,OAAe;IACxC,4FAA4F;IACnF,mBAAmB,GAAE,OAAe;IAC7C,qFAAqF;IAC5E,SAAS,GAAE,OAAe;IACnC,yDAAyD;IAChD,GAAG,GAAE,eAAwB;IAGxC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB;CAiBxF;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B"}

package/dist/tool-calls/client-capabilities.js

@@ -0,0 +1,43 @@
+import { AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_RAW_INPUT_RENDERING_CAPABILITY, clientSupportsAirCapability, isAirClient, } from "../air-extension.js";
+/**
+ * The client choices that decide the shape of a tool call report.
+ *
+ * The agent reads them once from `initialize.clientCapabilities`. The public
+ * `toAcpNotifications` functions take the ACP capabilities and read them on
+ * each call. The {@link AcpToolCallRenderer} reads nothing else, so one object
+ * holds every capability choice of a tool call report.
+ */
+export class ClientCapabilities {
+    terminalOutput;
+    terminalOutputDelta;
+    diffPatch;
+    air;
+    constructor(
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    terminalOutput = false, 
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    terminalOutputDelta = false, 
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    diffPatch = false, 
+    /** The capabilities that only JetBrains AIR declares. */
+    air = NO_AIR) {
+        this.terminalOutput = terminalOutput;
+        this.terminalOutputDelta = terminalOutputDelta;
+        this.diffPatch = diffPatch;
+        this.air = air;
+    }
+    static from(capabilities) {
+        const meta = capabilities?._meta;
+        const terminalOutputDelta = meta?.["terminal_output_delta"] === true;
+        return new ClientCapabilities(terminalOutputDelta || meta?.["terminal_output"] === true, terminalOutputDelta, clientSupportsAirCapability(capabilities, AIR_DIFF_PATCH_CAPABILITY), {
+            client: isAirClient(capabilities),
+            rawInputRendering: clientSupportsAirCapability(capabilities, AIR_RAW_INPUT_RENDERING_CAPABILITY),
+            planFile: clientSupportsAirCapability(capabilities, AIR_PLAN_FILE_CAPABILITY),
+        });
+    }
+}
+const NO_AIR = {
+    client: false,
+    rawInputRendering: false,
+    planFile: false,
+};

package/dist/tool-calls/content.d.ts

@@ -0,0 +1,59 @@
+import type { ContentBlock, ToolCallContent } from "@agentclientprotocol/sdk";
+import { DocumentBlockParam, ImageBlockParam, TextBlockParam, ToolResultBlockParam, WebSearchResultBlock, WebSearchToolResultBlockParam, WebSearchToolResultError } from "@anthropic-ai/sdk/resources";
+import { BetaBashCodeExecutionResultBlock, BetaBashCodeExecutionToolResultBlockParam, BetaBashCodeExecutionToolResultError, BetaCodeExecutionResultBlock, BetaCodeExecutionToolResultBlockParam, BetaCodeExecutionToolResultError, BetaImageBlockParam, BetaRequestMCPToolResultBlockParam, BetaTextEditorCodeExecutionCreateResultBlock, BetaTextEditorCodeExecutionStrReplaceResultBlock, BetaTextEditorCodeExecutionToolResultBlockParam, BetaTextEditorCodeExecutionToolResultError, BetaTextEditorCodeExecutionViewResultBlock, BetaToolReferenceBlock, BetaToolResultBlockParam, BetaToolSearchToolResultBlockParam, BetaToolSearchToolResultError, BetaToolSearchToolSearchResultBlock, BetaWebFetchBlock, BetaWebFetchToolResultBlockParam, BetaWebFetchToolResultErrorBlock, BetaWebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources/beta.mjs";
+/**
+ * Union of all possible content types that can appear in tool results from the Anthropic SDK.
+ * These are transformed to valid ACP ContentBlock types by toValidAcpContent().
+ */
+export type ToolResultContent = TextBlockParam | DocumentBlockParam | ImageBlockParam | BetaImageBlockParam | BetaToolReferenceBlock | BetaToolSearchToolSearchResultBlock | BetaToolSearchToolResultError | WebSearchResultBlock | WebSearchToolResultError | BetaWebFetchBlock | BetaWebFetchToolResultErrorBlock | BetaCodeExecutionResultBlock | BetaCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock | BetaBashCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock | BetaTextEditorCodeExecutionToolResultError;
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export declare function toDisplayPath(filePath: string, cwd?: string): string;
+/**
+ * Narrow the untyped message-level `tool_use_result` toward a per-tool Output
+ * shape: rejects everything but a plain non-null object (arrays pass a bare
+ * `typeof === "object"` check, so they're excluded here). The returned value
+ * is only *nominally* typed — it arrives over the wire from arbitrary CLI
+ * versions, so each caller must still guard the specific fields it reads
+ * before trusting them.
+ */
+export declare function structuredResult<T extends object>(toolUseResult: unknown): T | undefined;
+/** One display format for a web-search hit, shared by the structured
+ *  WebSearchOutput render and the server-side `web_search_result` block so
+ *  the two paths can't drift. */
+export declare function formatWebSearchHit(hit: {
+    title: string;
+    url: string;
+}): string;
+export declare function toAcpContentUpdate(content: any, isError?: boolean): {
+    content?: ToolCallContent[];
+};
+export declare function toAcpContentBlock(content: ToolResultContent, isError: boolean): ContentBlock;
+export declare function markdownEscape(text: string): string;
+/** Every SDK block that reports the result of a tool use. */
+export type ToolResultBlock = ToolResultBlockParam | BetaToolResultBlockParam | BetaWebSearchToolResultBlockParam | BetaWebFetchToolResultBlockParam | WebSearchToolResultBlockParam | BetaCodeExecutionToolResultBlockParam | BetaBashCodeExecutionToolResultBlockParam | BetaTextEditorCodeExecutionToolResultBlockParam | BetaRequestMCPToolResultBlockParam | BetaToolSearchToolResultBlockParam;
+/** One text content block. */
+export declare function textContent(text: string): ToolCallContent;
+/** The result text that the model saw, as the result to show. */
+export declare function resultText(result: {
+    content?: unknown;
+    is_error?: boolean | null;
+}): {
+    content?: ToolCallContent[];
+};
+/**
+ * The marker fields of a PostToolUse `tool_response` that clients read.
+ *
+ * The full `tool_response` repeats the tool output. A Read holds the whole
+ * file, a Bash holds stdout and stderr, and a Write holds the content. The
+ * tool-call content already carries that output. JetBrains AIR reads
+ * `status` and `isAsync` to detect an async subagent launch, so only those
+ * fields stay. Returns undefined when neither field is present.
+ */
+export declare function toolResponseMarkers(toolResponse: unknown): {
+    status?: string;
+    isAsync?: boolean;
+} | undefined;
+//# sourceMappingURL=content.d.ts.map

package/dist/tool-calls/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/tool-calls/content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,wBAAwB,EACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,gCAAgC,EAChC,yCAAyC,EACzC,oCAAoC,EACpC,4BAA4B,EAC5B,qCAAqC,EACrC,gCAAgC,EAChC,mBAAmB,EACnB,kCAAkC,EAClC,4CAA4C,EAC5C,gDAAgD,EAChD,+CAA+C,EAC/C,0CAA0C,EAC1C,0CAA0C,EAC1C,sBAAsB,EACtB,wBAAwB,EACxB,kCAAkC,EAClC,6BAA6B,EAC7B,mCAAmC,EACnC,iBAAiB,EACjB,gCAAgC,EAChC,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,sCAAsC,CAAC;AAG9C;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,kBAAkB,GAClB,eAAe,GACf,mBAAmB,GACnB,sBAAsB,GACtB,mCAAmC,GACnC,6BAA6B,GAC7B,oBAAoB,GACpB,wBAAwB,GACxB,iBAAiB,GACjB,gCAAgC,GAChC,4BAA4B,GAC5B,gCAAgC,GAChC,gCAAgC,GAChC,oCAAoC,GACpC,0CAA0C,GAC1C,4CAA4C,GAC5C,gDAAgD,GAChD,0CAA0C,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQpE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS,CAMxF;AAED;;iCAEiC;AACjC,wBAAgB,kBAAkB,CAAC,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE9E;AAUD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,GAAG,EACZ,OAAO,GAAE,OAAe,GACvB;IAAE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;CAAE,CA+BjC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CA6F5F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,wBAAwB,GACxB,iCAAiC,GACjC,gCAAgC,GAChC,6BAA6B,GAC7B,qCAAqC,GACrC,yCAAyC,GACzC,+CAA+C,GAC/C,kCAAkC,GAClC,kCAAkC,CAAC;AAEvC,8BAA8B;AAC9B,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG;IACpF,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B,CAEA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,OAAO,GACpB;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAUpD"}

package/dist/tool-calls/content.js

@@ -0,0 +1,194 @@
+import path from "node:path";
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export function toDisplayPath(filePath, cwd) {
+    if (!cwd)
+        return filePath;
+    const resolvedCwd = path.resolve(cwd);
+    const resolvedFile = path.resolve(filePath);
+    if (resolvedFile.startsWith(resolvedCwd + path.sep) || resolvedFile === resolvedCwd) {
+        return path.relative(resolvedCwd, resolvedFile);
+    }
+    return filePath;
+}
+/**
+ * Narrow the untyped message-level `tool_use_result` toward a per-tool Output
+ * shape: rejects everything but a plain non-null object (arrays pass a bare
+ * `typeof === "object"` check, so they're excluded here). The returned value
+ * is only *nominally* typed — it arrives over the wire from arbitrary CLI
+ * versions, so each caller must still guard the specific fields it reads
+ * before trusting them.
+ */
+export function structuredResult(toolUseResult) {
+    return toolUseResult !== null &&
+        typeof toolUseResult === "object" &&
+        !Array.isArray(toolUseResult)
+        ? toolUseResult
+        : undefined;
+}
+/** One display format for a web-search hit, shared by the structured
+ *  WebSearchOutput render and the server-side `web_search_result` block so
+ *  the two paths can't drift. */
+export function formatWebSearchHit(hit) {
+    return `${hit.title} (${hit.url})`;
+}
+/** Human-readable size for the document placeholder ("312 B", "2.4 KB",
+ *  "1.3 MB"). */
+function formatByteSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function toAcpContentUpdate(content, isError = false) {
+    if (Array.isArray(content) && content.length > 0) {
+        return {
+            content: content.map((c) => ({
+                type: "content",
+                content: toAcpContentBlock(c, isError),
+            })),
+        };
+    }
+    else if (typeof content === "object" && content !== null && "type" in content) {
+        return {
+            content: [
+                {
+                    type: "content",
+                    content: toAcpContentBlock(content, isError),
+                },
+            ],
+        };
+    }
+    else if (typeof content === "string" && content.length > 0) {
+        return {
+            content: [
+                {
+                    type: "content",
+                    content: {
+                        type: "text",
+                        text: isError ? `\`\`\`\n${content}\n\`\`\`` : content,
+                    },
+                },
+            ],
+        };
+    }
+    return {};
+}
+export function toAcpContentBlock(content, isError) {
+    const wrapText = (text) => ({
+        type: "text",
+        text: isError ? `\`\`\`\n${text}\n\`\`\`` : text,
+    });
+    switch (content.type) {
+        case "text":
+            return {
+                type: "text",
+                text: isError ? `\`\`\`\n${content.text}\n\`\`\`` : content.text,
+            };
+        case "image":
+            if (content.source.type === "base64") {
+                return {
+                    type: "image",
+                    data: content.source.data,
+                    mimeType: content.source.media_type,
+                };
+            }
+            // URL and file-based images can't be converted to ACP format (requires data)
+            return wrapText(content.source.type === "url"
+                ? `[image: ${content.source.url}]`
+                : "[image: file reference]");
+        case "document": {
+            // A PDF Read delivers its raw `document` block inside the tool_result
+            // content (SDK 0.3.243 moved it here from a separate follow-up user
+            // message; the MultiRead documents lane always lived here). ACP has no
+            // document block and the base64 payload can be megabytes — render a
+            // compact placeholder, never the data, matching the CLI's own compact
+            // "Read PDF (size)" rendering.
+            const title = typeof content.title === "string" && content.title.length > 0 ? ` "${content.title}"` : "";
+            const source = content.source;
+            switch (source.type) {
+                case "url":
+                    return wrapText(`[document${title}: ${source.url}]`);
+                case "base64":
+                case "text":
+                    // base64 inflates the byte count by 4/3; plain text is 1:1.
+                    return wrapText(`[document${title}: ${source.media_type}, ${formatByteSize(source.type === "base64"
+                        ? Math.floor((source.data.length * 3) / 4)
+                        : source.data.length)}]`);
+                default:
+                    return wrapText(`[document${title}]`);
+            }
+        }
+        case "tool_reference":
+            return wrapText(`Tool: ${content.tool_name}`);
+        case "tool_search_tool_search_result":
+            return wrapText(`Tools found: ${content.tool_references.map((r) => r.tool_name).join(", ") || "none"}`);
+        case "tool_search_tool_result_error":
+            return wrapText(`Error: ${content.error_code}${content.error_message ? ` - ${content.error_message}` : ""}`);
+        case "web_search_result":
+            return wrapText(formatWebSearchHit(content));
+        case "web_search_tool_result_error":
+            return wrapText(`Error: ${content.error_code}`);
+        case "web_fetch_result":
+            return wrapText(`Fetched: ${content.url}`);
+        case "web_fetch_tool_result_error":
+            return wrapText(`Error: ${content.error_code}`);
+        case "code_execution_result":
+            return wrapText(`Output: ${content.stdout || content.stderr || ""}`);
+        case "bash_code_execution_result":
+            return wrapText(`Output: ${content.stdout || content.stderr || ""}`);
+        case "code_execution_tool_result_error":
+        case "bash_code_execution_tool_result_error":
+            return wrapText(`Error: ${content.error_code}`);
+        case "text_editor_code_execution_view_result":
+            return wrapText(content.content);
+        case "text_editor_code_execution_create_result":
+            return wrapText(content.is_file_update ? "File updated" : "File created");
+        case "text_editor_code_execution_str_replace_result":
+            return wrapText(content.lines?.join("\n") || "");
+        case "text_editor_code_execution_tool_result_error":
+            return wrapText(`Error: ${content.error_code}${content.error_message ? ` - ${content.error_message}` : ""}`);
+        default:
+            return wrapText(JSON.stringify(content));
+    }
+}
+export function markdownEscape(text) {
+    let escape = "```";
+    for (const [m] of text.matchAll(/^```+/gm)) {
+        while (m.length >= escape.length) {
+            escape += "`";
+        }
+    }
+    return escape + "\n" + text + (text.endsWith("\n") ? "" : "\n") + escape;
+}
+/** One text content block. */
+export function textContent(text) {
+    return { type: "content", content: { type: "text", text } };
+}
+/** The result text that the model saw, as the result to show. */
+export function resultText(result) {
+    return toAcpContentUpdate(result.content, result.is_error === true);
+}
+/**
+ * The marker fields of a PostToolUse `tool_response` that clients read.
+ *
+ * The full `tool_response` repeats the tool output. A Read holds the whole
+ * file, a Bash holds stdout and stderr, and a Write holds the content. The
+ * tool-call content already carries that output. JetBrains AIR reads
+ * `status` and `isAsync` to detect an async subagent launch, so only those
+ * fields stay. Returns undefined when neither field is present.
+ */
+export function toolResponseMarkers(toolResponse) {
+    if (!toolResponse || typeof toolResponse !== "object" || Array.isArray(toolResponse)) {
+        return undefined;
+    }
+    const { status, isAsync } = toolResponse;
+    const markers = {
+        ...(typeof status === "string" ? { status } : {}),
+        ...(typeof isAsync === "boolean" ? { isAsync } : {}),
+    };
+    return Object.keys(markers).length > 0 ? markers : undefined;
+}

package/dist/tool-calls/facts.d.ts

@@ -0,0 +1,116 @@
+import type { ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
+import type { ClientCapabilities } from "./client-capabilities.js";
+/** A tool use as the SDK reports it. */
+export interface ToolUse {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/**
+ * The facts of a tool use, read once from its input. The
+ * {@link AcpToolCallRenderer} decides which ACP field carries each fact.
+ */
+export interface ToolUseFacts {
+    /** A short label. Not the input and not the output. */
+    title: string;
+    kind: ToolKind;
+    locations?: ToolCallLocation[];
+    /** The file change that the input makes, as diff content. */
+    change?: ToolCallContent[];
+    /**
+     * The input keys whose text a diff holds: {@link change}, or for a Write of a
+     * client with diffPatch, the approval preview or the hook patch. `rawInput`
+     * leaves them out.
+     */
+    fileTextKeys?: readonly string[];
+    /**
+     * A display copy of the input that the user reads: a plan, a subagent
+     * prompt, a question, a command description. A client that renders
+     * `rawInput` itself gets no display copy.
+     */
+    display?: ToolCallContent[];
+    /** The tool runs a command. Its output goes to the terminal channel. */
+    command?: boolean;
+    /**
+     * The absolute path of the plan file that holds the plan text of the input.
+     * Set only for a `planFile` client and an existing file. `rawInput` then
+     * carries this path and not the plan text.
+     */
+    planFilePath?: string;
+}
+/** The output of a command, for the terminal channel. */
+export interface CommandOutput {
+    output: string;
+    exitCode: number;
+}
+/**
+ * The facts of a tool result, read once from the SDK tool_result.
+ *
+ * `rawOutput` is present when the reporter decided what the raw output is.
+ * Otherwise the renderer sends the raw tool_result as `rawOutput` only when
+ * nothing else carries the result.
+ */
+export interface ToolResultFacts {
+    title?: string;
+    /** The result to show. */
+    content?: ToolCallContent[];
+    /** The final locations of an edit. */
+    locations?: ToolCallLocation[];
+    /** The output of a command. */
+    command?: CommandOutput;
+    /** A result that has no display form. */
+    rawOutput?: unknown;
+    /** The plan file of the tool use, as {@link ToolUseFacts.planFilePath} defines it. */
+    planFilePath?: string;
+    /**
+     * The plan is done with its file: the user approved it and the session left
+     * Plan mode. AIR then gets the clear signal of the plan file.
+     */
+    planFileReleased?: boolean;
+}
+/** What a reporter reads besides the input of the tool use. */
+export interface ToolUseContext {
+    cwd?: string;
+    capabilities: ClientCapabilities;
+    /**
+     * True when the tool use comes from the history of a loaded session. The
+     * files on disk then show a later state, so a reporter must not read them.
+     */
+    replay?: boolean;
+}
+/** What a reporter reads to report a tool result. */
+export interface ToolResultContext {
+    toolUse: ToolUse;
+    /** The SDK tool_result block. */
+    result: {
+        content?: unknown;
+        is_error?: boolean | null;
+        tool_use_id?: string;
+    };
+    /** The structured `tool_use_result` of the SDK message, when it is known. */
+    structured?: unknown;
+    capabilities: ClientCapabilities;
+}
+/**
+ * Turns the SDK data of one tool kind into tool facts. A reporter holds no
+ * state and knows nothing about the ACP fields.
+ */
+export interface ToolReporter {
+    toolUse(input: unknown, context: ToolUseContext): ToolUseFacts;
+    /**
+     * The facts of a successful result. Without this method, the result text
+     * that the model saw is the result to show.
+     */
+    toolResult?(context: ToolResultContext): ToolResultFacts;
+    /**
+     * The facts of an error result. Without this method, the error text is the
+     * result to show.
+     */
+    errorResult?(context: ToolResultContext): ToolResultFacts | undefined;
+    /**
+     * The facts of the PostToolUse hook `tool_response`: the final file change
+     * of an edit tool.
+     */
+    hookResult?(toolResponse: unknown, context: ToolUseContext): Promise<ToolResultFacts>;
+}
+//# sourceMappingURL=facts.d.ts.map

package/dist/tool-calls/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/tool-calls/facts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,wCAAwC;AACxC,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,sCAAsC;IACtC,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,kBAAkB,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/E,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,kBAAkB,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,YAAY,CAAC;IAC/D;;;OAGG;IACH,UAAU,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAAC;IACzD;;;OAGG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,GAAG,SAAS,CAAC;IACtE;;;OAGG;IACH,UAAU,CAAC,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACvF"}

package/dist/tool-calls/facts.js

@@ -0,0 +1 @@
+export {};

package/dist/tool-calls/field-tracker.d.ts

@@ -0,0 +1,58 @@
+import type { SessionNotification, ToolCallContent } from "@agentclientprotocol/sdk";
+type SessionUpdate = SessionNotification["update"];
+/**
+ * Remembers what the client holds for each open tool call, so that a
+ * `tool_call_update` carries only the fields that changed.
+ *
+ * A client overwrites a field that an update carries and merges `_meta` by
+ * key. An update that repeats a field value therefore only costs bandwidth,
+ * and for a Write it repeats the whole file. The tracker drops such fields.
+ * It never drops `_meta`, because a client appends `terminal_output_delta`
+ * data.
+ *
+ * An entry starts at the `tool_call` and ends after both the tool_result and
+ * the PostToolUse hook callback, or when the session is torn down.
+ */
+export declare class ToolCallFieldTracker {
+    private readonly calls;
+    /**
+     * Records a `tool_call`, or removes the unchanged fields of a
+     * `tool_call_update` and records the rest.
+     *
+     * Returns false when the update carries nothing new: no replaced field
+     * remains, `_meta` has no key besides `claudeCode` and `jetbrains`, and
+     * every `claudeCode` and `jetbrains.air` key repeats its value. The caller
+     * then skips the update. An update for a tool call that the tracker does
+     * not know passes through unchanged.
+     *
+     * `replacePinnedContent` lets the final result of the tool replace an exact
+     * approval patch (see {@link pinContent}).
+     */
+    apply(update: SessionUpdate, options?: {
+        replacePinnedContent?: boolean;
+    }): boolean;
+    /**
+     * Records the exact approval patch that the client shows for a tool call.
+     *
+     * The streamed tool input later refines the call with a standard diff of
+     * the Edit snippet. That diff must not replace the exact patch, so the
+     * content stays until an update passes `replacePinnedContent`.
+     */
+    pinContent(toolCallId: string, content: ToolCallContent[]): void;
+    /**
+     * Marks the tool_result of a tool call. The entry ends now, or after the
+     * PostToolUse hook callback when `hookPending` is true.
+     */
+    finishResult(toolCallId: string, hookPending: boolean): void;
+    /**
+     * Marks the end of the PostToolUse hook callback of a tool call. The entry
+     * ends when the tool_result was seen. Otherwise the tool_result ends it.
+     */
+    finishHook(toolCallId: string): void;
+    /** Forgets one tool call. */
+    delete(toolCallId: string): void;
+    /** Forgets every tool call, when the session is torn down. */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=field-tracker.d.ts.map

package/dist/tool-calls/field-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-tracker.d.ts","sourceRoot":"","sources":["../../src/tool-calls/field-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAErF,KAAK,aAAa,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AA+BnD;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IAEzD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO;IA8CnF;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI;IAOhE;;;OAGG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI;IAO5D;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIpC,6BAA6B;IAC7B,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIhC,8DAA8D;IAC9D,KAAK,IAAI,IAAI;CAGd"}