@agentclientprotocol/claude-agent-acp 0.67.0 → 0.69.0

package/dist/acp-agent.js

@@ -11,11 +11,14 @@ import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
 import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
 import { SettingsManager } from "./settings.js";
+import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.js";
+import { AGENT_FILE_CHANGE_REPORT_CAPABILITY, agentFileChangeReportMeta, agentFileChangeReportRequestId, containsFileChangeAuditMarker, createFileChangeAuditSupport, createFileChangeAuditTurnState, FILE_CHANGE_AUDIT_SERVER_NAME, isFileChangeAuditReportPhase, isFileChangeAuditTool, supportsAgentFileChangeReport, } from "./file-change-audit.js";
 import { applyTaskCreate, applyTaskList, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const execFileAsync = promisify(execFile);
 const MAX_TITLE_LENGTH = 256;
+const MAX_INLINE_FAILURE_TITLE_LENGTH = 256;
 function sanitizeTitle(text) {
     // Replace newlines and collapse whitespace
     const sanitized = text
@@ -146,130 +149,13 @@ function computeSessionFingerprint(params) {
     const servers = [...(params.mcpServers ?? [])].sort((a, b) => a.name.localeCompare(b.name));
     return JSON.stringify({ cwd: params.cwd, mcpServers: servers });
 }
-/**
- * The single provider ID this agent exposes via `providers/*`. Claude Code has
- * one LLM backend selected by protocol (anthropic / bedrock / vertex), so there
- * is exactly one configurable provider.
- */
-const PROVIDER_ID = "main";
-/**
- * Protocols the `main` provider can be configured with. These mirror the
- * env-var mappings understood by {@link createEnvForProvider}.
- */
 const SUPPORTED_PROTOCOLS = ["anthropic", "bedrock", "vertex"];
+const PROVIDER_ID = "main";
+const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com";
 const SUBAGENT_TRANSCRIPT_CAPABILITY = "subagent-transcript";
-// This is a protocol namespace, not user-facing branding: `jetbrains` owns the
-// non-standard contract and `air` identifies the client defining its rendering
-// semantics, without affecting unrelated JetBrains ACP clients.
-const JETBRAINS_META_KEY = "jetbrains";
-const AIR_META_KEY = "air";
-const AIR_EXTENSION_VERSION_KEY = "version";
-const AIR_EXTENSION_CAPABILITIES_KEY = "capabilities";
-const AIR_SESSION_FAILURE_KEY = "sessionFailure";
-const AIR_EXTENSION_VERSION = 1;
 function supportsSubagentTranscript(capabilities) {
     return capabilities?._meta?.[SUBAGENT_TRANSCRIPT_CAPABILITY] === true;
 }
-const AIR_FAILURE_PRESENTATION = {
-    // A non-fatal notice whose wording comes from the adapter or the SDK, so this message is only the
-    // fallback for an advisory published without one.
-    advisory: {
-        message: "Claude reported a notice.",
-        retryable: false,
-        actions: [],
-    },
-    auth_required: {
-        message: "Sign in to continue using Claude.",
-        retryable: false,
-        actions: ["login"],
-    },
-    bad_request: {
-        message: "Claude could not process this request.",
-        retryable: false,
-        actions: ["new_turn"],
-    },
-    budget_exhausted: {
-        message: "This Claude session reached its configured budget.",
-        retryable: false,
-        actions: ["new_session"],
-    },
-    context_exhausted: {
-        message: "This Claude turn reached its configured limit.",
-        retryable: false,
-        actions: ["new_turn"],
-    },
-    internal_error: {
-        message: "Claude Agent encountered an internal error.",
-        retryable: true,
-        actions: ["retry"],
-    },
-    overloaded: {
-        message: "Claude is temporarily overloaded.",
-        retryable: true,
-        actions: ["retry"],
-    },
-    provider_error: {
-        message: "The model provider reported an error.",
-        retryable: true,
-        actions: ["retry"],
-    },
-    quota_exhausted: {
-        message: "The Claude account has no available quota.",
-        retryable: false,
-        actions: ["new_session"],
-    },
-    rate_limited: {
-        message: "Claude is temporarily rate limited.",
-        retryable: true,
-        actions: ["retry"],
-    },
-    transport_lost: {
-        message: "The connection to Claude was lost.",
-        retryable: false,
-        actions: ["new_session"],
-    },
-    worker_shutdown: {
-        message: "The Claude worker is shutting down.",
-        retryable: false,
-        actions: ["new_session"],
-    },
-};
-function supportsAirSessionFailures(capabilities) {
-    const jetbrains = capabilities?._meta?.[JETBRAINS_META_KEY];
-    const air = jetbrains?.[AIR_META_KEY];
-    const version = air?.[AIR_EXTENSION_VERSION_KEY];
-    const advertised = air?.[AIR_EXTENSION_CAPABILITIES_KEY];
-    return (typeof version === "number" &&
-        Number.isFinite(version) &&
-        Number.isInteger(version) &&
-        version >= AIR_EXTENSION_VERSION &&
-        Array.isArray(advertised) &&
-        advertised.some((capability) => capability === AIR_SESSION_FAILURE_KEY));
-}
-function providerFailureCategory(errorKind) {
-    switch (errorKind) {
-        case "authentication_failed":
-        case "oauth_org_not_allowed":
-            return "auth_required";
-        case "billing_error":
-            return "quota_exhausted";
-        case "rate_limit":
-            return "rate_limited";
-        case "overloaded":
-            return "overloaded";
-        case "invalid_request":
-        case "model_not_found":
-            return "bad_request";
-        case "max_output_tokens":
-            return "context_exhausted";
-        case "server_error":
-        case "unknown":
-        case undefined:
-            return "provider_error";
-        default:
-            return "provider_error";
-    }
-}
 function parentToolUseIdOf(message) {
     if (!("parent_tool_use_id" in message))
         return null;
@@ -690,9 +576,7 @@ export class ClaudeAcpAgent {
     clientCapabilities;
     logger;
     gatewayAuthRequest;
-    /** Client-managed LLM routing set via `providers/set`. Process-scoped and
-     *  never persisted to disk (see the Configurable LLM Providers RFD). When
-     *  set, it takes precedence over {@link gatewayAuthRequest}. */
+    /** Set while ACP overrides the agent's native provider configuration. */
     providerConfig;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
@@ -846,12 +730,7 @@ export class ClaudeAcpAgent {
             // steering extension contract: advertises the `_session/steering` request
             // so clients know they may inject a follow-up into a running turn.
             _meta: {
-                [JETBRAINS_META_KEY]: {
-                    [AIR_META_KEY]: {
-                        [AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
-                        [AIR_EXTENSION_CAPABILITIES_KEY]: [AIR_SESSION_FAILURE_KEY],
-                    },
-                },
+                ...airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY),
                 steering: {
                     supported: true,
                 },
@@ -965,21 +844,13 @@ export class ClaudeAcpAgent {
         }
         throw new Error("Method not implemented.");
     }
-    /**
-     * `providers/list` — returns the single client-configurable custom gateway
-     * provider (`main`). `current` carries only non-secret routing (never headers,
-     * which may hold secrets); only `apiType`/`baseUrl` are surfaced for UI
-     * display, and is `null` when the provider is not configured/disabled. The
-     * provider is optional (`required: false`): while disabled/unconfigured the
-     * agent falls back to its own default routing (normal Claude login).
-     */
     async unstable_listProviders(_params) {
-        const config = this.resolveProviderConfig();
+        const config = this.providerConfig ?? this.defaultProviderConfig();
         const provider = {
             providerId: PROVIDER_ID,
             supported: SUPPORTED_PROTOCOLS,
             required: false,
-            current: config ? { apiType: config.apiType, baseUrl: config.baseUrl } : null,
+            current: { apiType: config.apiType, baseUrl: config.baseUrl },
         };
         return { providers: [provider] };
     }
@@ -1021,30 +892,43 @@ export class ClaudeAcpAgent {
         return {};
     }
     /**
-     * `providers/disable` — disabling the `main` provider clears any client-managed
-     * routing (both a `providers/set` config and the legacy gateway auth request),
-     * so the agent reverts to its own default routing and `providers/list` reports
-     * `current: null`. Disabling any other (unknown) ID is treated as a successful
-     * no-op per the RFD's idempotency rule.
+     * `providers/disable` ends ACP ownership of the single mutually exclusive
+     * backend slot and restores the agent's native routing state.
      */
     async unstable_disableProvider(params) {
         if (params.providerId === PROVIDER_ID) {
             this.providerConfig = undefined;
-            this.gatewayAuthRequest = undefined;
         }
         // Unknown provider: idempotent success.
         return {};
     }
-    /**
-     * Resolve the effective client-managed routing config. `providers/set` takes
-     * precedence; otherwise fall back to the legacy gateway auth request. Returns
-     * `null` when neither is configured.
-     */
     resolveProviderConfig() {
-        if (this.providerConfig) {
-            return this.providerConfig;
+        return this.providerConfig ?? gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+    }
+    defaultProviderConfig() {
+        const gatewayConfig = gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+        if (gatewayConfig) {
+            return gatewayConfig;
         }
-        return gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+        if (process.env.CLAUDE_CODE_USE_BEDROCK) {
+            return {
+                apiType: "bedrock",
+                baseUrl: process.env.ANTHROPIC_BEDROCK_BASE_URL ?? "https://bedrock-runtime.amazonaws.com",
+                headers: {},
+            };
+        }
+        if (process.env.CLAUDE_CODE_USE_VERTEX) {
+            return {
+                apiType: "vertex",
+                baseUrl: process.env.ANTHROPIC_VERTEX_BASE_URL ?? "https://aiplatform.googleapis.com",
+                headers: {},
+            };
+        }
+        return {
+            apiType: "anthropic",
+            baseUrl: process.env.ANTHROPIC_BASE_URL ?? DEFAULT_ANTHROPIC_BASE_URL,
+            headers: {},
+        };
     }
     async logout(_params) {
         // Clear in-memory gateway credentials supplied via `authenticate` and any
@@ -1094,6 +978,15 @@ export class ClaudeAcpAgent {
         // user message, so the consumer can't promote the turn from the echo.
         const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
         const isLocalOnlyCommand = firstText.startsWith("/") && LOCAL_ONLY_COMMANDS.has(firstText.split(" ", 1)[0]);
+        const fileChangeReportRequestId = supportsAgentFileChangeReport(this.clientCapabilities)
+            ? agentFileChangeReportRequestId(params._meta)
+            : undefined;
+        let fileChangeAudit;
+        if (fileChangeReportRequestId &&
+            !session.fileChangeReportRequestIds.has(fileChangeReportRequestId)) {
+            session.fileChangeReportRequestIds.add(fileChangeReportRequestId);
+            fileChangeAudit = createFileChangeAuditTurnState(fileChangeReportRequestId);
+        }
         // Each prompt is a Turn whose deferred the persistent consumer settles once
         // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
         // turn, pushes the user message onto the streaming input, makes sure the
@@ -1101,6 +994,7 @@ export class ClaudeAcpAgent {
         const turn = {
             promptUuid,
             isLocalOnlyCommand,
+            ...(fileChangeAudit ? { fileChangeAudit } : {}),
             settled: false,
             resolve: () => { },
             reject: () => { },
@@ -1264,6 +1158,15 @@ export class ClaudeAcpAgent {
         await this.publishGoalFromPrompt(sessionId, firstText, steeredUuid);
         return { outcome: "injected" };
     }
+    /** Publish the audit terminal for every turn path that did not reach the
+     *  report tool. The support flips the turn state synchronously before its
+     *  transport await, so callers can stay fail-open and settle the ACP prompt
+     *  immediately without allowing a racing lifecycle path to publish twice. */
+    finishFileChangeAudit(session, turn, reason) {
+        if (!turn.fileChangeAudit || !session.fileChangeAuditSupport)
+            return;
+        void session.fileChangeAuditSupport.finishUnavailable(turn.fileChangeAudit, reason);
+    }
     /** Lazily start the per-session consumer that drains the SDK query stream for
      *  the session's whole life. Idempotent: only the first `prompt()` starts it. */
     ensureConsumer(session, sessionId) {
@@ -1298,6 +1201,8 @@ export class ClaudeAcpAgent {
         // it here so the subsequent `RequestError.internalError` can forward it to
         // clients as structured `data`, sparing them from pattern-matching on text.
         let lastAssistantError;
+        let lastAssistantWasUsageLimit = false;
+        let lastAssistantFailureTitle;
         // When a streaming classifier refuses a turn, the assistant message carries
         // stop_reason "refusal" and structured stop_details. We capture the
         // human-readable explanation so the terminal `result` can surface it.
@@ -1343,6 +1248,14 @@ export class ClaudeAcpAgent {
          *  as the turn's answer. */
         const sendUpdate = async (notification) => {
             const { update } = notification;
+            if (isFileChangeAuditReportPhase(session.activeTurn?.fileChangeAudit) &&
+                (update.sessionUpdate === "agent_message_chunk" ||
+                    update.sessionUpdate === "agent_thought_chunk" ||
+                    update.sessionUpdate === "user_message_chunk" ||
+                    update.sessionUpdate === "tool_call" ||
+                    update.sessionUpdate === "tool_call_update")) {
+                return;
+            }
             if (update.sessionUpdate === "agent_message_chunk") {
                 const claudeMeta = update._meta?.claudeCode;
                 if (!claudeMeta?.parentToolUseId) {
@@ -1351,113 +1264,41 @@ export class ClaudeAcpAgent {
             }
             await this.client.sessionUpdate(notification);
         };
-        const isAdvisory = (failure) => failure.severity === "warning";
-        const failureRevisions = new Map();
-        const sessionFailureEpoch = randomUUID();
-        const activeSessionFailures = new Map();
         let pendingWorkerShutdown = false;
         const isCurrentConsumer = () => this.sessions[params.sessionId] === session;
-        const sessionFailureMeta = (failure, phase) => {
-            const presentation = AIR_FAILURE_PRESENTATION[failure.category];
-            return {
-                [JETBRAINS_META_KEY]: {
-                    [AIR_META_KEY]: {
-                        [AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
-                        [AIR_SESSION_FAILURE_KEY]: {
-                            id: failure.id,
-                            revision: failure.revision,
-                            phase,
-                            category: failure.category,
-                            source: "claude",
-                            safeMessage: failure.safeMessage ?? presentation.message,
-                            retryable: presentation.retryable,
-                            actions: presentation.actions,
-                            ...(failure.turnId ? { turnId: failure.turnId } : {}),
-                            ...(failure.severity ? { severity: failure.severity } : {}),
-                        },
-                    },
-                },
-            };
-        };
-        const emitSessionFailure = async (failure, phase) => {
-            if (!isCurrentConsumer()) {
-                this.logger.error(`Session ${params.sessionId}: ignored AIR session failure from a stale query consumer`);
-                return false;
-            }
-            try {
-                await sendUpdate({
-                    sessionId: params.sessionId,
-                    update: {
-                        sessionUpdate: "session_info_update",
-                        _meta: sessionFailureMeta(failure, phase),
-                    },
-                });
-                return true;
-            }
-            catch (error) {
-                this.logger.error(`Session ${params.sessionId}: failed to publish AIR session failure: ${error}`);
-                return false;
-            }
-        };
-        const clearSessionFailure = async (shouldClear = () => true) => {
-            if (!supportsAirSessionFailures(this.clientCapabilities))
-                return;
-            for (const failure of [...activeSessionFailures.values()]) {
-                if (!shouldClear(failure))
-                    continue;
-                const cleared = {
-                    ...failure,
-                    revision: failure.revision + 1,
-                };
-                if (await emitSessionFailure(cleared, "cleared")) {
-                    failureRevisions.set(cleared.id, cleared.revision);
-                    activeSessionFailures.delete(cleared.id);
-                }
-            }
-        };
-        const createSessionFailure = async (category, options = {}) => {
-            if (!supportsAirSessionFailures(this.clientCapabilities) || !isCurrentConsumer()) {
-                return undefined;
-            }
-            // An advisory is not a failure of the turn: it keeps its own id namespace and its own slot, so
-            // it neither clears an actionable error nor is cleared by one. Only the newest advisory
-            // matters, so they all share one id and bump its revision.
-            if (category === "advisory") {
-                const id = `${params.sessionId}:notice:${sessionFailureEpoch}`;
-                return {
-                    id,
-                    revision: (failureRevisions.get(id) ?? 0) + 1,
-                    category,
-                    severity: "warning",
-                    ...(options.safeMessage ? { safeMessage: options.safeMessage } : {}),
-                };
-            }
+        const sessionFailures = new SessionFailureController({
+            sessionId: params.sessionId,
+            state: session.sessionFailureState,
+            capabilities: this.clientCapabilities,
+            isCurrent: isCurrentConsumer,
+            sendUpdate,
+            logger: this.logger,
+        });
+        const createSessionFailure = async (kind, options = {}) => {
             const turnId = options.turnScoped === false ? undefined : session.activeTurn?.promptUuid;
-            const id = turnId
-                ? `${turnId}:error`
-                : `${params.sessionId}:session-error:${sessionFailureEpoch}`;
-            await clearSessionFailure((failure) => failure.id !== id && !isAdvisory(failure));
-            return {
-                id,
-                revision: (failureRevisions.get(id) ?? 0) + 1,
-                category,
-                ...(turnId ? { turnId } : {}),
-            };
+            return sessionFailures.prepare(kind, {
+                turnId,
+                sessionScoped: options.turnScoped === false,
+                title: options.title,
+                details: options.details,
+                severity: options.severity,
+            });
         };
-        const publishSessionFailure = async (category, options = {}) => {
-            const failure = await createSessionFailure(category, options);
-            if (!failure)
-                return;
-            if (await emitSessionFailure(failure, "active")) {
-                failureRevisions.set(failure.id, failure.revision);
-                activeSessionFailures.set(failure.id, failure);
-            }
+        const publishSessionFailure = async (kind, options = {}) => {
+            const turnId = options.turnScoped === false ? undefined : session.activeTurn?.promptUuid;
+            await sessionFailures.publish(kind, {
+                turnId,
+                sessionScoped: options.turnScoped === false,
+                title: options.title,
+                details: options.details,
+                severity: options.severity,
+            });
         };
         const clearFailuresFromEarlierTurns = async () => {
             const activeTurnId = session.activeTurn?.promptUuid;
             // Advisories carry no turnId, so without the guard every turn boundary would sweep them away.
             // They are session-scoped and stay until superseded or dismissed by the user.
-            await clearSessionFailure((failure) => failure.turnId !== activeTurnId && !isAdvisory(failure));
+            await sessionFailures.clear((failure) => failure.recoveryPolicy === "next_attempt" && failure.turnId !== activeTurnId);
         };
         const internalErrorForClient = (data, rawDetail) => RequestError.internalError(data, supportsAirSessionFailures(this.clientCapabilities) ? undefined : rawDetail);
         const resetTurnScratch = () => {
@@ -1465,6 +1306,8 @@ export class ClaudeAcpAgent {
             lastAssistantUsage = null;
             lastAssistantModel = null;
             lastAssistantError = undefined;
+            lastAssistantWasUsageLimit = false;
+            lastAssistantFailureTitle = undefined;
             lastRefusalExplanation = null;
             compactionInProgress = false;
             // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
@@ -1708,11 +1551,14 @@ export class ClaudeAcpAgent {
         };
         /** Settle the active turn's deferred exactly once, disarm the force-cancel
          *  backstop (the turn is over), and drop it from the queue. */
-        const settleActive = (result) => {
+        const settleActive = (result, auditReason = result.stopReason === "cancelled"
+            ? "cancelled"
+            : "notReported") => {
             const turn = session.activeTurn;
             if (!turn || turn.settled) {
                 return;
             }
+            this.finishFileChangeAudit(session, turn, auditReason);
             // Captured before the settled flip below (isHeldOpen tests !settled).
             const wasHeld = isHeldOpen(turn);
             turn.settled = true;
@@ -1746,6 +1592,7 @@ export class ClaudeAcpAgent {
                 this.logger.error(`Session ${params.sessionId}: cannot fail active turn because no unsettled active turn exists: ${error}`);
                 return;
             }
+            this.finishFileChangeAudit(session, turn, "providerError");
             turn.settled = true;
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
@@ -1760,28 +1607,27 @@ export class ClaudeAcpAgent {
         /** Complete a negotiated terminal failure on the prompt response itself,
          *  which is the canonical AIR carrier. Legacy clients keep the historical
          *  JSON-RPC rejection path. */
-        const failActiveWithSessionFailure = async (category, error) => {
+        const failActiveWithSessionFailure = async (kind, error, title) => {
             if (!supportsAirSessionFailures(this.clientCapabilities)) {
                 failActive(error);
                 return;
             }
             if (!session.activeTurn || session.activeTurn.settled) {
-                this.logger.error(`Session ${params.sessionId}: cannot attach ${category} to a prompt response because no active turn exists; publishing a session-scoped failure`);
-                await publishSessionFailure(category, { turnScoped: false });
+                this.logger.error(`Session ${params.sessionId}: cannot attach ${kind} to a prompt response because no active turn exists; publishing a session-scoped failure`);
+                await publishSessionFailure(kind, { turnScoped: false, title });
                 return;
             }
-            const failure = await createSessionFailure(category);
+            const failure = await createSessionFailure(kind, { title });
             if (!failure) {
                 failActive(error);
                 return;
             }
-            failureRevisions.set(failure.id, failure.revision);
-            activeSessionFailures.set(failure.id, failure);
+            sessionFailures.recordActive(failure);
             settleActive({
                 stopReason: "end_turn",
                 usage: sessionUsage(session),
-                _meta: sessionFailureMeta(failure, "active"),
-            });
+                _meta: sessionFailureMeta(failure),
+            }, "providerError");
         };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
@@ -1793,6 +1639,7 @@ export class ClaudeAcpAgent {
             session.turnQueue = [];
             for (const turn of turns) {
                 if (!turn.settled) {
+                    this.finishFileChangeAudit(session, turn, "providerError");
                     const wasHeld = isHeldOpen(turn);
                     turn.settled = true;
                     if (wasHeld) {
@@ -1941,6 +1788,7 @@ export class ClaudeAcpAgent {
                     // still here was enqueued afterward and was not part of the cancel.)
                     for (const queued of [...(session.turnQueue ?? [])]) {
                         if (!queued.settled) {
+                            this.finishFileChangeAudit(session, queued, "providerError");
                             queued.settled = true;
                             queued.reject(RequestError.internalError(undefined, SESSION_ENDED_MESSAGE));
                         }
@@ -2278,7 +2126,7 @@ export class ClaudeAcpAgent {
                                         // the next prompt; only a timer could tell those apart.
                                         this.logger.error(`Session ${params.sessionId}: SDK went idle without emitting a result ` +
                                             `for the active turn; failing the in-flight prompt (issue #825)`);
-                                        await failActiveWithSessionFailure("internal_error", RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE));
+                                        await failActiveWithSessionFailure("internal_error", RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE), TURN_NO_RESULT_MESSAGE);
                                     }
                                     // The SDK generates the session title in a background task and
                                     // persists it to the session file; `idle` is the turn-over
@@ -2505,10 +2353,21 @@ export class ClaudeAcpAgent {
                             }
                             case "plugin_install":
                             case "notification":
-                            case "api_retry":
                             case "thinking_tokens":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
+                            case "api_retry": {
+                                const title = message.error_status === null
+                                    ? `Reconnecting to Claude, attempt ${message.attempt} of ${message.max_retries}.`
+                                    : `Retrying Claude, attempt ${message.attempt} of ${message.max_retries}.`;
+                                await publishSessionFailure(message.error_status === null
+                                    ? "transport_lost"
+                                    : providerFailureCategory(message.error), {
+                                    title,
+                                    severity: "warning",
+                                });
+                                break;
+                            }
                             case "model_refusal_fallback": {
                                 // The SDK retried a refused turn on the fallback model and made
                                 // the swap persistent for the session. Without a notice the
@@ -2534,21 +2393,28 @@ export class ClaudeAcpAgent {
                                 const category = message.api_refusal_category
                                     ? ` (${message.api_refusal_category})`
                                     : "";
-                                const explanation = message.api_refusal_explanation
-                                    ? `\n\n${message.api_refusal_explanation}`
-                                    : "";
                                 const outcome = persistent
                                     ? `The session will continue on ${message.fallback_model}.`
                                     : local
                                         ? `Only that response came from ${message.fallback_model}; the session stays on ${message.original_model}.`
                                         : `The session stays on ${message.original_model}.`;
-                                const fallbackNotice = `${message.original_model} declined this request${category}; ` +
-                                    `retried with ${message.fallback_model}. ${outcome}${explanation}`;
+                                const fallbackSummary = `${message.original_model} declined this request${category}; ` +
+                                    `retried with ${message.fallback_model}. ${outcome}`;
+                                const explanation = message.api_refusal_explanation || undefined;
+                                const fallbackNotice = explanation
+                                    ? `${fallbackSummary}\n\n${explanation}`
+                                    : fallbackSummary;
                                 // A silent model swap is a session-level advisory, not something the model said.
                                 // Clients that negotiated typed records get it as one; the rest keep the bold-label
                                 // transcript line, which was the only way to flag it before.
                                 if (supportsAirSessionFailures(this.clientCapabilities)) {
-                                    await publishSessionFailure("advisory", { safeMessage: fallbackNotice });
+                                    const useDetails = explanation !== undefined &&
+                                        fallbackSummary.length + 2 + explanation.length >
+                                            MAX_INLINE_FAILURE_TITLE_LENGTH;
+                                    await publishSessionFailure("advisory", {
+                                        title: useDetails ? fallbackSummary : fallbackNotice,
+                                        ...(useDetails ? { details: explanation } : {}),
+                                    });
                                 }
                                 else {
                                     await sendUpdate({
@@ -2872,13 +2738,15 @@ export class ClaudeAcpAgent {
                                 settleOrDefer({ stopReason: "end_turn", usage: sessionUsage(session) });
                                 break;
                             }
-                            if (!message.is_error) {
-                                await clearSessionFailure();
+                            if (!message.is_error && lastAssistantModel !== null) {
+                                const activeTurnId = session.activeTurn?.promptUuid;
+                                await sessionFailures.clear((failure) => failure.recoveryPolicy === "real_model_success" ||
+                                    (failure.severity === "warning" && failure.turnId === activeTurnId));
                             }
                             switch (message.subtype) {
                                 case "success": {
                                     if (message.result.includes("Please run /login")) {
-                                        await failActiveWithSessionFailure("auth_required", RequestError.authRequired());
+                                        await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), message.result);
                                         break;
                                     }
                                     if (message.stop_reason === "max_tokens") {
@@ -2886,7 +2754,7 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError), internalErrorForClient(errorKindData(lastAssistantError), message.result));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError, lastAssistantWasUsageLimit), internalErrorForClient(errorKindData(lastAssistantError), message.result), lastAssistantFailureTitle ?? message.result);
                                         break;
                                     }
                                     // The result text is forwarded in two cases. Local-only
@@ -2922,7 +2790,7 @@ export class ClaudeAcpAgent {
                                         break;
                                     }
                                     if (message.is_error) {
-                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError), internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure(providerFailureCategory(lastAssistantError, lastAssistantWasUsageLimit), internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), lastAssistantFailureTitle ?? (message.errors.join(", ") || message.subtype));
                                         break;
                                     }
                                     stopReason = "end_turn";
@@ -2930,21 +2798,21 @@ export class ClaudeAcpAgent {
                                 }
                                 case "error_max_budget_usd":
                                     if (message.is_error) {
-                                        await failActiveWithSessionFailure("budget_exhausted", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure("budget_exhausted", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
                                         break;
                                     }
                                     stopReason = "max_turn_requests";
                                     break;
                                 case "error_max_turns":
                                     if (message.is_error) {
-                                        await failActiveWithSessionFailure("provider_error", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure("context_exhausted", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
                                         break;
                                     }
                                     stopReason = "max_turn_requests";
                                     break;
                                 case "error_max_structured_output_retries":
                                     if (message.is_error) {
-                                        await failActiveWithSessionFailure("provider_error", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        await failActiveWithSessionFailure("provider_error", internalErrorForClient(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype), message.errors.join(", ") || message.subtype);
                                         break;
                                     }
                                     stopReason = "max_turn_requests";
@@ -3218,6 +3086,10 @@ export class ClaudeAcpAgent {
                         if (message.type === "assistant" && message.parent_tool_use_id === null) {
                             lastAssistantUsage = snapshotFromUsage(message.message.usage);
                             lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+                            lastAssistantWasUsageLimit = isSyntheticUsageLimitMessage(message.message);
+                            if (message.error || lastAssistantWasUsageLimit) {
+                                lastAssistantFailureTitle = assistantMessageText(message.message);
+                            }
                             if (message.message.model && message.message.model !== "<synthetic>") {
                                 lastAssistantModel = message.message.model;
                             }
@@ -3276,7 +3148,18 @@ export class ClaudeAcpAgent {
                             break;
                         }
                         if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
-                            await failActiveWithSessionFailure("auth_required", RequestError.authRequired());
+                            await failActiveWithSessionFailure("auth_required", RequestError.authRequired(), assistantMessageText(message.message));
+                            break;
+                        }
+                        // AIR receives this provider condition on the terminal prompt
+                        // response as a typed failure whose title is the exact assistant
+                        // error text captured above. Do not duplicate that text as an
+                        // ordinary assistant message; legacy clients retain the historical
+                        // transcript behavior.
+                        if (message.type === "assistant" &&
+                            message.parent_tool_use_id === null &&
+                            (message.error || isSyntheticUsageLimitMessage(message.message)) &&
+                            supportsAirSessionFailures(this.clientCapabilities)) {
                             break;
                         }
                         let content;
@@ -3452,7 +3335,7 @@ export class ClaudeAcpAgent {
                         break;
                     case "auth_status":
                         if (!message.isAuthenticating && message.error === undefined) {
-                            await clearSessionFailure((failure) => failure.category === "auth_required");
+                            await sessionFailures.clear((failure) => failure.kind === "auth_required");
                         }
                         break;
                     default:
@@ -3568,6 +3451,7 @@ export class ClaudeAcpAgent {
         if (session.turnQueue) {
             for (const turn of session.turnQueue) {
                 if (turn !== session.activeTurn && !turn.settled) {
+                    this.finishFileChangeAudit(session, turn, "cancelled");
                     turn.settled = true;
                     // Deliberately no `usage`: a queued turn never ran, so the session
                     // accumulator (the active turn's tally) is not its spend.
@@ -3629,6 +3513,7 @@ export class ClaudeAcpAgent {
         {
             const active = session.activeTurn;
             if (isHeldOpen(active)) {
+                this.finishFileChangeAudit(session, active, "cancelled");
                 active.settled = true;
                 // Mirror settleActive's invariants (it is consumer-scoped and
                 // unreachable from here): disarm the backstop — none should be
@@ -3951,9 +3836,35 @@ export class ClaudeAcpAgent {
     async replaySessionHistory(sessionId) {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
-        const forwardSubagentText = this.sessions[sessionId]?.forwardSubagentText ??
-            supportsSubagentTranscript(this.clientCapabilities);
+        const session = this.sessions[sessionId];
+        const forwardSubagentText = session?.forwardSubagentText ?? supportsSubagentTranscript(this.clientCapabilities);
+        const supportsTypedFailures = supportsAirSessionFailures(this.clientCapabilities);
+        const activeUsageLimit = supportsTypedFailures ? activeUsageLimitMessage(messages) : undefined;
+        const sessionFailures = session && supportsTypedFailures
+            ? new SessionFailureController({
+                sessionId,
+                state: session.sessionFailureState,
+                capabilities: this.clientCapabilities,
+                isCurrent: () => this.sessions[sessionId] === session,
+                sendUpdate: (notification) => this.client.sessionUpdate(notification),
+                logger: this.logger,
+            })
+            : undefined;
+        let replayTurnId;
+        // Stop-hook additionalContext is persisted as an internal user message.
+        // Once that marker (or the internal tool itself) appears, suppress the
+        // whole audit exchange until its tool result. This also hides a disobedient
+        // model's separate prose message, while an ordinary next user prompt safely
+        // ends an incomplete audit lane.
+        let replayingFileChangeAudit = false;
+        const replayFileChangeAuditToolUseIds = new Set();
         for (const message of messages) {
+            if (message.type === "user" &&
+                message.parent_tool_use_id === null &&
+                typeof message.uuid === "string" &&
+                message.uuid.length > 0) {
+                replayTurnId = message.uuid;
+            }
             // Backfill the ACP messageId -> SDK uuid mapping for messages we didn't
             // observe live (resumed/loaded sessions), so rewind/resume can translate
             // a client-supplied id without an extra getSessionMessages read. Not read
@@ -3969,6 +3880,21 @@ export class ClaudeAcpAgent {
             if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
                 continue;
             }
+            // Capable clients saw every synthetic usage-limit message as a typed
+            // failure live, so replay it at the same transcript position. The
+            // preceding persisted user uuid is the live prompt uuid and therefore
+            // recreates the same incident identity. Only the latest limit not
+            // followed by a real model answer remains active internally.
+            if (sessionFailures &&
+                message.type === "assistant" &&
+                message.parent_tool_use_id === null &&
+                isSyntheticUsageLimitMessage(message.message)) {
+                const title = assistantMessageText(message.message);
+                if (title) {
+                    await sessionFailures.restore(replayTurnId ? `${replayTurnId}:error` : `${sessionId}:history-error:${message.uuid}`, "quota_exhausted", title, message.uuid === activeUsageLimit?.uuid);
+                }
+                continue;
+            }
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
             const parentToolUseId = parentToolUseIdOf(message);
@@ -3981,6 +3907,57 @@ export class ClaudeAcpAgent {
                 if (content === null)
                     continue;
             }
+            const auditBlocks = Array.isArray(content)
+                ? content.filter((block) => typeof block === "object" && block !== null)
+                : [];
+            const hasFileChangeAuditMarker = (typeof content === "string" && containsFileChangeAuditMarker(content)) ||
+                auditBlocks.some((block) => typeof block.text === "string" && containsFileChangeAuditMarker(block.text));
+            const fileChangeAuditToolUseIds = auditBlocks.flatMap((block) => (block.type === "tool_use" ||
+                block.type === "server_tool_use" ||
+                block.type === "mcp_tool_use") &&
+                typeof block.name === "string" &&
+                isFileChangeAuditTool(block.name) &&
+                typeof block.id === "string"
+                ? [block.id]
+                : []);
+            const replayMessageRole = message.message
+                ?.role;
+            if (hasFileChangeAuditMarker || fileChangeAuditToolUseIds.length > 0) {
+                replayingFileChangeAudit = true;
+                for (const toolUseId of fileChangeAuditToolUseIds) {
+                    replayFileChangeAuditToolUseIds.add(toolUseId);
+                }
+                continue;
+            }
+            if (replayingFileChangeAudit) {
+                const toolResultIds = auditBlocks.flatMap((block) => (block.type === "tool_result" || block.type === "mcp_tool_result") &&
+                    typeof block.tool_use_id === "string"
+                    ? [block.tool_use_id]
+                    : []);
+                let completedReport = false;
+                for (const toolUseId of toolResultIds) {
+                    if (replayFileChangeAuditToolUseIds.delete(toolUseId))
+                        completedReport = true;
+                }
+                if (completedReport && replayFileChangeAuditToolUseIds.size === 0) {
+                    replayingFileChangeAudit = false;
+                    continue;
+                }
+                // A denied attempt to call another tool is still part of the hidden
+                // lane. Its result must not end replay suppression before the report.
+                if (toolResultIds.length > 0) {
+                    continue;
+                }
+                // The next real user prompt is already represented by the client and
+                // starts a new turn; do not let a missing audit result hide it or the
+                // rest of the replay.
+                if (replayMessageRole === "user") {
+                    replayingFileChangeAudit = false;
+                }
+                else {
+                    continue;
+                }
+            }
             for (const notification of toAcpNotifications(
             // @ts-expect-error - untyped in SDK but we handle all of these
             content, 
@@ -4074,6 +4051,26 @@ export class ClaudeAcpAgent {
                     message: "Session not found",
                 };
             }
+            const fileChangeAudit = session.activeTurn?.fileChangeAudit;
+            if (isFileChangeAuditReportPhase(fileChangeAudit)) {
+                // The hidden continuation is an audit-only lane: it may submit the
+                // wrapper-owned report, but it must not run another command after the
+                // user-visible answer has already completed.
+                if (isFileChangeAuditTool(toolName) && fileChangeAudit?.phase === "collecting") {
+                    return { behavior: "allow", updatedInput: toolInput };
+                }
+                return {
+                    behavior: "deny",
+                    message: "Only the internal file-change report is allowed during the audit.",
+                };
+            }
+            // The tool is intentionally unusable outside a negotiated audit turn.
+            if (isFileChangeAuditTool(toolName)) {
+                return {
+                    behavior: "deny",
+                    message: "No file-change report was requested for this turn.",
+                };
+            }
             // When the tool call originates inside a subagent, attribute the eagerly
             // emitted tool_call (and the permission request itself) to the Agent/Task
             // tool call that spawned the subagent, mirroring the streamed subagent
@@ -4771,6 +4768,30 @@ export class ClaudeAcpAgent {
         // below) so the TaskCreated/TaskCompleted hook callbacks can close over
         // the same Map that the streaming message handler will read from.
         const taskState = new Map();
+        // Resolve every workspace root once. The hidden report tool uses this same
+        // set for lexical path validation, and the SDK receives it below.
+        const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
+        const additionalDirectories = [
+            ...(userProvidedOptions?.additionalDirectories ?? []),
+            ...acpAdditionalDirectories,
+        ];
+        const fileChangeAuditSupport = supportsAgentFileChangeReport(this.clientCapabilities)
+            ? createFileChangeAuditSupport({
+                cwd: params.cwd,
+                additionalDirectories,
+                getActiveState: () => this.sessions[sessionId]?.activeTurn?.fileChangeAudit,
+                publish: async (result) => {
+                    await this.client.sessionUpdate({
+                        sessionId,
+                        update: {
+                            sessionUpdate: "session_info_update",
+                            _meta: agentFileChangeReportMeta(result),
+                        },
+                    });
+                },
+                logError: (message) => this.logger.error(message),
+            })
+            : undefined;
         // The exact env the query will be created with. Built (and the provider
         // cache key derived from it, below) in one place so the key always
         // describes the backend this query actually talks to: `providers/set`,
@@ -4814,7 +4835,13 @@ export class ClaudeAcpAgent {
             cwd: params.cwd,
             includePartialMessages: true,
             forwardSubagentText,
-            mcpServers: { ...(userProvidedOptions?.mcpServers || {}), ...mcpServers },
+            mcpServers: {
+                ...(userProvidedOptions?.mcpServers || {}),
+                ...mcpServers,
+                ...(fileChangeAuditSupport
+                    ? { [FILE_CHANGE_AUDIT_SERVER_NAME]: fileChangeAuditSupport.mcpServer }
+                    : {}),
+            },
             // If we want bypassPermissions to be an option, we have to allow it here.
             // But it doesn't work in root mode, so we only activate it if it will work.
             allowDangerouslySkipPermissions: ALLOW_BYPASS,
@@ -4848,6 +4875,14 @@ export class ClaudeAcpAgent {
             tools,
             hooks: {
                 ...userProvidedOptions?.hooks,
+                ...(fileChangeAuditSupport
+                    ? {
+                        PreToolUse: [
+                            ...(userProvidedOptions?.hooks?.PreToolUse || []),
+                            { hooks: [fileChangeAuditSupport.preToolUseHook] },
+                        ],
+                    }
+                    : {}),
                 PostToolUse: [
                     ...(userProvidedOptions?.hooks?.PostToolUse || []),
                     {
@@ -4867,6 +4902,14 @@ export class ClaudeAcpAgent {
                         ],
                     },
                 ],
+                ...(fileChangeAuditSupport
+                    ? {
+                        Stop: [
+                            ...(userProvidedOptions?.hooks?.Stop || []),
+                            { hooks: [fileChangeAuditSupport.stopHook] },
+                        ],
+                    }
+                    : {}),
                 TaskCreated: [
                     ...(userProvidedOptions?.hooks?.TaskCreated || []),
                     {
@@ -4897,11 +4940,7 @@ export class ClaudeAcpAgent {
         // legacy `_meta.additionalRoots` extension for clients that haven't been
         // updated yet. Either source is merged with directories supplied via
         // `_meta.claudeCode.options.additionalDirectories` (SDK pass-through).
-        const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
-        options.additionalDirectories = [
-            ...(userProvidedOptions?.additionalDirectories ?? []),
-            ...acpAdditionalDirectories,
-        ];
+        options.additionalDirectories = additionalDirectories;
         if (creationOpts?.resume === undefined || creationOpts?.forkSession) {
             // Set our own session id if not resuming an existing session.
             options.sessionId = sessionId;
@@ -5113,6 +5152,9 @@ export class ClaudeAcpAgent {
             emittedAssistantText: false,
             owedTrailingIdles: 0,
             messageIdToUuid: new Map(),
+            sessionFailureState: createSessionFailureState(),
+            fileChangeReportRequestIds: new Set(),
+            fileChangeAuditSupport,
         };
         return {
             sessionId,
@@ -6099,7 +6141,7 @@ function isTaskTool(toolName) {
  *  permission-surfaced tool_call for them (see `ensureToolCallEmitted`) must be
  *  resolved explicitly at tool_result time. */
 function shouldEmitToolCall(toolName) {
-    return toolName !== "TodoWrite" && !isTaskTool(toolName);
+    return toolName !== "TodoWrite" && !isTaskTool(toolName) && !isFileChangeAuditTool(toolName);
 }
 /** Build the Claude Code-specific metadata for a tool call. Bash descriptions
  *  are kept out of ACP's standard `title`, which clients may use as the shell
@@ -6252,7 +6294,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     const registerHooks = options?.registerHooks !== false;
     const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
     if (typeof content === "string") {
-        if (content.length === 0) {
+        if (content.length === 0 || containsFileChangeAuditMarker(content)) {
             return [];
         }
         const update = {
@@ -6286,6 +6328,13 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     // Unlike `tool_use_result`, entries carry their own tool_use_id, so batched
     // messages need no single-block guard.
     const toolResultMeta = parseToolResultMeta(options?.toolResultMeta);
+    // A report-phase assistant message may contain a short text preface and the
+    // internal tool call in the same content array. Hide the whole message, not
+    // only the tool block, so it stays absent on session replay as well as live.
+    const containsFileChangeAuditToolUse = content.some((chunk) => (chunk.type === "tool_use" ||
+        chunk.type === "server_tool_use" ||
+        chunk.type === "mcp_tool_use") &&
+        isFileChangeAuditTool(chunk.name));
     const output = [];
     // Only handle the first chunk for streaming; extend as needed for batching
     for (const chunk of content) {
@@ -6293,7 +6342,9 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
         switch (chunk.type) {
             case "text":
             case "text_delta": {
-                if (chunk.text) {
+                if (chunk.text &&
+                    !containsFileChangeAuditToolUse &&
+                    !containsFileChangeAuditMarker(chunk.text)) {
                     update = {
                         sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
                         content: {
@@ -6305,21 +6356,22 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 break;
             }
             case "image":
-                update = {
-                    sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
-                    content: {
-                        type: "image",
-                        data: chunk.source.type === "base64" ? chunk.source.data : "",
-                        mimeType: chunk.source.type === "base64" ? chunk.source.media_type : "",
-                        uri: chunk.source.type === "url" ? chunk.source.url : undefined,
-                    },
-                };
+                if (!containsFileChangeAuditToolUse)
+                    update = {
+                        sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
+                        content: {
+                            type: "image",
+                            data: chunk.source.type === "base64" ? chunk.source.data : "",
+                            mimeType: chunk.source.type === "base64" ? chunk.source.media_type : "",
+                            uri: chunk.source.type === "url" ? chunk.source.url : undefined,
+                        },
+                    };
                 break;
             case "thinking":
             case "thinking_delta": {
                 // Recent models default `thinking.display` to "omitted", which streams
                 // signature-only thinking blocks whose text is empty.
-                if (chunk.thinking) {
+                if (chunk.thinking && !containsFileChangeAuditToolUse) {
                     update = {
                         sessionUpdate: "agent_thought_chunk",
                         content: {
@@ -6335,7 +6387,11 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "mcp_tool_use": {
                 const alreadyCached = chunk.id in toolUseCache;
                 toolUseCache[chunk.id] = chunk;
-                if (chunk.name === "TodoWrite") {
+                if (isFileChangeAuditTool(chunk.name)) {
+                    // Wrapper-owned audit protocol: never surface or register generic
+                    // PostToolUse callbacks for the internal tool.
+                }
+                else if (chunk.name === "TodoWrite") {
                     // @ts-expect-error - sometimes input is empty object or undefined
                     if (Array.isArray(chunk.input?.todos)) {
                         update = {
@@ -6459,6 +6515,10 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     logger.error(`[claude-agent-acp] Got a tool result for tool use that wasn't tracked: ${chunk.tool_use_id}`);
                     break;
                 }
+                if (isFileChangeAuditTool(toolUse.name)) {
+                    delete toolUseCache[chunk.tool_use_id];
+                    break;
+                }
                 // A permission request may have surfaced a plan-rendered (TodoWrite) or
                 // suppressed (Task*) tool as a real tool_call so the request referenced
                 // a tool call the client knows about (see `ensureToolCallEmitted`,