@@ -313,6 +313,8 @@ const WORKFLOW_MEMBER_TRANSCRIPT_FLUSH_MS = 500;
313313// A steer waits at most this long, from its request, for its foreground
314314// subagents to move to the background before it is sent.
315315const BACKGROUND_MOVE_TIMEOUT_MS = 5_000 ;
316+ // Matches the stderr tail the SDK keeps for a CLI it spawns itself.
317+ const CLAUDE_STDERR_TAIL_LENGTH = 2_048 ;
316318
317319const CLAUDE_GROUP_WATCH_SCRIPT = [
318320 "{ trap '' TERM; read -r _ <&3; kill -TERM 0; sleep 5; kill -KILL 0; } </dev/null >/dev/null 2>&1 &" ,
@@ -330,18 +332,23 @@ const CLAUDE_GROUP_WATCH_SCRIPT = [
330332 * (#23370), so a watcher in the group reads a pipe only this server holds and stops the group at
331333 * its end-of-file.
332334 */
333- export function spawnClaudeProcessGroup ( options : ClaudeSpawnOptions ) : ClaudeSpawnedProcess {
335+ export function spawnClaudeProcessGroup (
336+ options : ClaudeSpawnOptions ,
337+ onStderr : ( text : string ) => void = ( ) => { } ,
338+ ) : ClaudeSpawnedProcess {
334339 const child = NodeChildProcess . spawn (
335340 "/bin/sh" ,
336341 [ "-c" , CLAUDE_GROUP_WATCH_SCRIPT , "t3-claude" , options . command , ...options . args ] ,
337342 {
338343 cwd : options . cwd ,
339344 env : options . env ,
340345 signal : options . signal ,
341- stdio : [ "pipe" , "pipe" , "ignore " , "pipe" ] ,
346+ stdio : [ "pipe" , "pipe" , "pipe " , "pipe" ] ,
342347 detached : true ,
343348 } ,
344349 ) ;
350+ // Always drained, so a chatty CLI never blocks on a full stderr pipe.
351+ child . stderr ?. setEncoding ( "utf8" ) . on ( "data" , onStderr ) ;
345352 child . once ( "exit" , ( ) => {
346353 try {
347354 signalProcessGroup ( child . pid ?? 0 , "SIGKILL" ) ;
@@ -532,6 +539,18 @@ export class ClaudeAgentSdkQueryRunnerError extends Schema.TaggedError<ClaudeAge
532539 }
533540}
534541
542+ export class ClaudeCodeStartupError extends Schema . TaggedError < ClaudeCodeStartupError > ( ) (
543+ "ClaudeCodeStartupError" ,
544+ {
545+ stderr : Schema . String ,
546+ cause : Schema . optional ( Schema . Defect ( ) ) ,
547+ } ,
548+ ) {
549+ override get message ( ) : string {
550+ return `Claude Code exited before it started: ${ this . stderr } ` ;
551+ }
552+ }
553+
535554export class ClaudeBackgroundWorkBlocksQueryReplacementError extends Schema . TaggedError < ClaudeBackgroundWorkBlocksQueryReplacementError > ( ) (
536555 "ClaudeBackgroundWorkBlocksQueryReplacementError" ,
537556 { } ,
@@ -942,10 +961,22 @@ export const layerQueryRunner: Layer.Layer<
942961 pathToClaudeCodeExecutable : launch . command ,
943962 executableArgs : [ ...launch . args , ...( queryOptions . executableArgs ?? [ ] ) ] ,
944963 } ;
964+ // Only a CLI that fails before its first message explains itself on
965+ // stderr, such as refusing bypassPermissions as root (#15882); later
966+ // stderr stays out of turn failures.
967+ let stderrTail = "" ;
968+ let answered = false ;
969+ const appendStderr = ( text : string ) => {
970+ if ( answered ) return ;
971+ stderrTail = ( stderrTail + text ) . slice ( - CLAUDE_STDERR_TAIL_LENGTH ) ;
972+ } ;
945973 // Windows has no process groups, so there the SDK spawns the CLI itself.
946974 const spawnClaudeCodeProcess =
947975 options . spawnClaudeCodeProcess ??
948- ( platform === "win32" ? undefined : spawnClaudeProcessGroup ) ;
976+ ( platform === "win32"
977+ ? undefined
978+ : ( spawnOptions : ClaudeSpawnOptions ) =>
979+ spawnClaudeProcessGroup ( spawnOptions , appendStderr ) ) ;
949980 const queryRuntime = yield * Effect . uninterruptibleMask ( ( restore ) =>
950981 Effect . try ( {
951982 try : ( ) =>
@@ -1009,9 +1040,18 @@ export const layerQueryRunner: Layer.Layer<
10091040 ) ;
10101041
10111042 return {
1012- messages : Stream . fromAsyncIterable ( claudeQueryMessages ( queryRuntime ) , ( cause ) =>
1013- queryRunnerError ( cause , "fromAsyncIterable" ) ,
1014- ) . pipe (
1043+ messages : Stream . fromAsyncIterable ( claudeQueryMessages ( queryRuntime ) , ( cause ) => {
1044+ const stderr = answered ? "" : stderrTail . trim ( ) ;
1045+ return queryRunnerError (
1046+ stderr . length > 0 ? new ClaudeCodeStartupError ( { stderr, cause } ) : cause ,
1047+ "fromAsyncIterable" ,
1048+ ) ;
1049+ } ) . pipe (
1050+ Stream . tap ( ( ) =>
1051+ Effect . sync ( ( ) => {
1052+ answered = true ;
1053+ } ) ,
1054+ ) ,
10151055 Stream . tap ( ( message ) =>
10161056 logProtocolEvent ( {
10171057 direction : "incoming" ,
0 commit comments