Skip to content

Commit a1a19e0

Browse files
fix(server): show why the Claude CLI refused to start instead of "Provider turn failed"
Claude Code explains startup refusals, such as bypassPermissions under root, only on stderr, which the process-group spawner discarded. The spawner now drains stderr and keeps a 2 KB tail; a stream that fails before the CLI's first message carries it as ClaudeCodeStartupError, which the turn failure shows (redacted and bounded as before). Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 445487e commit a1a19e0

2 files changed

Lines changed: 47 additions & 6 deletions

File tree

‎apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -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.
315315
const 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

317319
const 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+
535554
export 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",

‎packages/provider-core/src/server/failure.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ function curatedCauseMessages(cause: unknown): {
9191
case "ClaudeBackgroundWorkBlocksQueryReplacementError":
9292
case "ClaudeAppendSystemPromptFileError":
9393
case "ClaudeAppendSystemPromptMissingValueError":
94+
case "ClaudeCodeStartupError":
9495
case "CursorModelUnavailableError":
9596
return { known: stringField(cause, "message"), category: categoryMessage() };
9697
case "ContextHandoffDeliveryUncertainError":

0 commit comments

Comments
 (0)