fix: allow opt-out of session_state_changed via env var

src/acp-agent.ts

@@ -123,6 +123,7 @@ type Session = {
   pendingMessages: Map<string, { resolve: (cancelled: boolean) => void; order: number }>;
   nextPendingOrder: number;
   abortController: AbortController;
+  useSessionStateEvents: boolean;
 };
 
 type BackgroundTerminal =
@@ -682,6 +683,12 @@ export class ClaudeAcpAgent implements Agent {
                 unreachable(message, this.logger);
                 break;
             }
+            // When session state events are disabled (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=0),
+            // session_state_changed(idle) will never arrive. Return immediately
+            // using the stopReason set by the result subtype above.
+            if (!session.useSessionStateEvents) {
+              return { stopReason, usage: sessionUsage(session) };
+            }
             break;
           }
           case "stream_event": {
@@ -1364,8 +1371,11 @@ export class ClaudeAcpAgent implements Agent {
         ...process.env,
         ...userProvidedOptions?.env,
         ...createEnvForGateway(this.gatewayAuthMeta),
-        // Opt-in to session state events like when the agent is idle
-        CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+        // Allow users to opt out of session state events by setting
+        // CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=0 in their environment,
+        // e.g. when the Claude Code binary does not support this feature.
+        CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS:
+          process.env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS ?? "1",
       },
       // Override certain fields that must be controlled by ACP
       cwd: params.cwd,
@@ -1520,6 +1530,8 @@ export class ClaudeAcpAgent implements Agent {
       pendingMessages: new Map(),
       nextPendingOrder: 0,
       abortController,
+      useSessionStateEvents:
+        (process.env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS ?? "1") !== "0",
     };
 
     return {

src/tests/acp-agent.test.ts

@@ -1348,6 +1348,7 @@ describe("stop reason propagation", () => {
       pendingMessages: new Map(),
       nextPendingOrder: 0,
       abortController: new AbortController(),
+      useSessionStateEvents: true,
     };
   }
 
@@ -1483,6 +1484,7 @@ describe("stop reason propagation", () => {
         cachedWriteTokens: 0,
       },
       abortController: new AbortController(),
+      useSessionStateEvents: true,
       configOptions: [],
       promptRunning: false,
       pendingMessages: new Map(),
@@ -1560,6 +1562,7 @@ describe("session/close", () => {
       pendingMessages: new Map(),
       nextPendingOrder: 0,
       abortController: new AbortController(),
+      useSessionStateEvents: true,
     };
     return agent.sessions[sessionId]!;
   }
@@ -1730,6 +1733,7 @@ describe("usage_update computation", () => {
       pendingMessages: new Map(),
       nextPendingOrder: 0,
       abortController: new AbortController(),
+      useSessionStateEvents: true,
     };
   }