fix(server): show why Claude refuses full access as root#23804

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

The Claude query runner captures up to 2,048 characters of CLI stderr before its first SDK message. If startup fails with the recognized root-permission refusal, it reports a typed error that provider failure handling preserves.

Changes: Claude startup diagnostics

Layer / File(s)	Summary
Capture bounded startup stderr apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts	The process-group spawner pipes stderr to an optional callback. The query runner retains a bounded stderr tail until the first SDK message.
Surface startup refusal in provider failures apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts, packages/provider-core/src/server/failure.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAgentSdkQueryRunner.test.ts	A pre-message failure becomes ClaudeCodeRootRefusalError when stderr contains the recognized refusal. Provider failure handling preserves its message. Tests check that unrelated stderr details are excluded.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related issues

Suggested reviewers: f4llenz

Root refusals receive a fixed explanation. The change is ready to merge, with an ordering test recommended.

Check name	Status	Explanation
Title check	Passed	The title names the main change: Claude's root refusal for full access is now surfaced to the user. It is specific, follows conventional commit form, and matches the description and linked issue #1588…
Description check	Passed	The description follows the repository template. It has Problem, Change, Scope and approval, and Verification sections. The problem and reproduction steps are clear, and the change is explained. Scope…
Linked Issues check	Passed	[#15882] is the only active direct link. Its expected behavior allows either Full access shown as unavailable or the turn failing with the CLI's own explanation. The PR implements the second option. I…
Out of Scope Changes check	Passed	The whole-PR diff against the merge base contains only changes that serve the root-refusal diagnostic. ClaudeAdapterV2.ts adds Duration import, the stderr tail constants, the onStderr and `onStd…

Full details: Title check

Explanation

The title names the main change: Claude's root refusal for full access is now surfaced to the user. It is specific, follows conventional commit form, and matches the description and linked issue #15882. The change is a diagnostic message on the server side, so the title is accurate.

Full details: Description check

Explanation

The description follows the repository template. It has Problem, Change, Scope and approval, and Verification sections. The problem and reproduction steps are clear, and the change is explained. Scope links the triaged issue #15882. Verification gives concrete test counts, a before/after regression result, a runtime proof table, typecheck and lint results, and provenance for the models and harnesses. The description is long and includes some review-process detail, but every required section is filled in with specifics.

Full details: Linked Issues check

Explanation

[#15882] is the only active direct link. Its expected behavior allows either Full access shown as unavailable or the turn failing with the CLI's own explanation. The PR implements the second option. In ClaudeAdapterV2.ts, non-Windows spawns now pipe stderr into appendStderr, which keeps a 2,048-character tail. The query runner handles a stream failure: while no SDK message has arrived (answered is false), it waits up to 1 second for stderr to close, then checks the tail for CLAUDE_ROOT_REFUSAL. On a match it wraps the failure in ClaudeCodeRootRefusalError. Its message is Claude Code exited before it started: --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons. packages/provider-core/src/server/failure.ts lists this error tag in curatedCauseMessages, so the message reaches the user. The wait on stderr close resolves the ordering uncertainty noted in the earlier review. The regression tests in ClaudeAgentSdkQueryRunner.test.ts run a fake CLI through a real subprocess. One test asserts the refusal text appears in the failure. A second asserts that a token and file path in other stderr do not appear. The PR does not set IS_SANDBOX=1 and does not change permission modes, which the issue asks it to avoid. The retry symptom (No conversation found) is tracked in #15854 and is not an expected behavior of this issue. Residual notes: the Windows branch passes no stderr callbacks, so it does not surface the refusal. Root is a Unix concept, and the issue reports a Linux host. The PR's runtime transcript and test output are external links; this review did not run them.

Full details: Out of Scope Changes check

Explanation

The whole-PR diff against the merge base contains only changes that serve the root-refusal diagnostic. ClaudeAdapterV2.ts adds Duration import, the stderr tail constants, the onStderr and onStderrClose parameters to spawnClaudeProcessGroup (defaults keep existing callers working), the ClaudeCodeRootRefusalError class with a required cause, and the Stream.catch wrap that replaces the original fromAsyncIterable error mapping. The answered flag stops stderr capture after the first message. failure.ts adds one allowlist case. ClaudeAgentSdkQueryRunner.test.ts adds the stream import and two regression tests that cover the same behavior. No unrelated product, permission, or UI change appears in the diff. The Windows spawn path changes only in that it was not given the callbacks; its behavior is otherwise unchanged. The PR description's issue-flow and triage references are administrative and add no code.

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR