fix(claude): expand slash commands when a message has attachments

[t3dotgg]

On the Claude provider, /skill args expanded normally on its own but was sent as literal text whenever the same message carried an image. The Claude CLI only treats a streamed user message as a slash command when the final content block is text, and the adapter put the text block first and appended image blocks after it.

buildUserMessageEffect now emits image blocks first and the text block last, so the command survives the attachment. Non-image file attachments never become content blocks, they reach the agent through the path line ProviderService writes into the prompt, and the regression test now covers that case too.

Supersedes #8271 by @lnieuwenhuis, rebased onto main. The rebase also needed a small test fix because attachmentRelativePath now returns string | null.

Closes #8013

Built by Claude Opus 5 in the Claude Code harness.

---

Note

Low Risk
Localized prompt assembly change in the Claude adapter with regression tests; affects message ordering to the SDK but not auth or persistence.

Overview
Fixes a regression where /skill args and similar slash commands were sent as literal text whenever the same user message included an image. The Claude CLI only treats a streamed user message as a command when the last content block is text; the adapter had been putting text first and appending image blocks after it.

buildUserMessageEffect now builds SDK content as optional leading prose (from $skill dispatch), then image blocks, then the final text block (command or full prompt). Non-image file attachments are unchanged—they still reach the agent via path lines in the prompt, not as content blocks.

Tests add readPromptMessages for multi-turn assertions, update the image-embedding expectation to image-then-text order, and cover slash commands with no attachment, with an image, and with a file attachment.

^{Reviewed by Cursor Bugbot for commit c02168a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix slash command expansion on messages with image attachments in ClaudeAdapter

• Reorders content-block construction in buildUserMessageEffect so image blocks are emitted before the final command or ordinary prompt text block, preventing attachments from suppressing slash command expansion.
• Adds test helpers and assertions in ClaudeAdapter.test.ts to read multiple queued prompt messages and verify image blocks precede the text block while non-image attachments remain text-only.
• Behavioral Change: buildUserMessageEffect now appends dispatched text after image blocks instead of before; messages without image blocks are unchanged.

^{Macroscope summarized c02168a.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.6 KiB	13.6 KiB	−17 B (−0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.0 KiB	+8 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.6 KiB	6.6 KiB	−25 B (−0.4%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	57.1 KiB	57.1 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	10	10	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.6 KiB	+66 B (+0.5%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.0 KiB	7.0 KiB	−3 B (−0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.5 KiB	6.6 KiB	+69 B (+1.0%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.8 KiB	57.9 KiB	+88 B (+0.1%)	66.4 KiB	✅
Claude	Live turn messages	8	10	+2 (+25.0%)	21	✅

Baseline: 4b26132 · PR result: c02168a · Source CI: success

Scenario and decoded snapshot size

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: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Approved at c02168a

Macroscope's review found this PR approvable — This is a focused Claude adapter bug fix that reorders image and text blocks so existing slash-command expansion continues to work with attachments. The production impact is confined to prompt construction, with targeted regression coverage and no defaults, schema, infrastructure, or sensitive-package changes.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate c02168a