Skip to content

fix: allow opt-out of session_state_changed via env var#498

Open
vincentye38 wants to merge 1 commit intoagentclientprotocol:mainfrom
vincentye38:fix/opt-out-session-state-events
Open

fix: allow opt-out of session_state_changed via env var#498
vincentye38 wants to merge 1 commit intoagentclientprotocol:mainfrom
vincentye38:fix/opt-out-session-state-events

Conversation

@vincentye38
Copy link
Copy Markdown

@vincentye38 vincentye38 commented Apr 1, 2026

Summary

  • Fixes prompt() hangs when Claude Code binary doesn't support CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS #497
  • When CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=0 is set in the environment, the prompt loop returns the PromptResponse directly from the result message handler instead of waiting for session_state_changed(idle) which will never arrive on older Claude Code binaries
  • The env var defaults to "1" (enabled) to preserve existing behavior
  • Respects user's env var instead of hardcoding "1", allowing deterministic opt-out

Changes

  1. Session.useSessionStateEvents — new boolean flag on the session, derived from the env var at session creation
  2. createSession env overrideCLAUDE_CODE_EMIT_SESSION_STATE_EVENTS now respects process.env instead of always hardcoding "1"
  3. Result handler fallback — after the inner result subtype switch, returns immediately when useSessionStateEvents is false

Test plan

  • With CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS unset (default): behavior unchanged, waits for session_state_changed(idle)
  • With CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=0: prompt returns immediately after result(success), no hang
  • With older Claude Code binary + env var set to 0: client receives PromptResponse and does not deadlock

When CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=0 is set in the environment,
return the PromptResponse directly from the result message handler
instead of waiting for session_state_changed(idle) which will never
arrive. This provides a deterministic fallback for Claude Code binaries
that do not support session state events.

The env var defaults to "1" (enabled) to preserve existing behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@josevalim
Copy link
Copy Markdown
Contributor

Do we want to support different versions of Claude Code or should we instead document that you need a minimum version? Especially because this seems to fix the problem only by explicitly setting an env var, which I assume has low discovery?

@vincentye38
Copy link
Copy Markdown
Author

CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS Is introduced in v2.1.83. The default is set to 0. IMO, We should maintain this acp agent downward compatible with 0 while supporting 1 until Claude Code SDK changes default setting to 1.

@vincentye38
Copy link
Copy Markdown
Author

@benbrandt Could you take a look at this PR. Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

prompt() hangs when Claude Code binary doesn't support CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS

2 participants