feat(cli): add audio bridge for attachments

docs/design/2026-08-01-audio-bridge.md

@@ -0,0 +1,32 @@
+# Audio bridge for user attachments
+
+## Context
+
+Qwen Code already transcribes ACP audio content blocks through the configured
+`voiceModel` when the primary model does not support audio. Interactive and
+headless `@` attachments do not use that path: file processing replaces an
+unsupported audio file with a placeholder before the CLI can transcribe it.
+
+## Design
+
+Extract the ACP-only conversion into a shared CLI audio-bridge service. The
+service accepts normalized prompt parts, keeps audio unchanged when the active
+primary model supports it, and otherwise replaces every audio part with an
+untrusted machine transcript produced by `voiceModel`. Missing configuration,
+oversized audio, empty transcripts, request failures, and cancellation never
+forward raw audio to a text-only primary model.
+
+Interactive and headless `@` resolution preserve unsupported audio only when a
+batch-capable `voiceModel` is selected, then run the shared bridge before the
+existing vision bridge. ACP direct audio blocks use the same service and keep
+their existing agent-message disclosure. A bridge notice identifies the voice
+model whenever audio left the machine, including failed or empty responses.
+
+The existing `voiceModel` setting and `/model --voice` command remain the sole
+configuration surface. Voice dictation behavior is unchanged.
+
+## Scope
+
+This change covers user-supplied ACP audio blocks and interactive/headless
+`@audio` attachments. Audio nested in tool results, channel-specific attachment
+plumbing, video, and realtime dictation are unchanged.

docs/users/configuration/settings.md

@@ -284,9 +284,9 @@ The `extra_body` field allows you to add custom parameters to the request body s
 
 #### voiceModel
 
-| Setting      | Type   | Description                                                                                                                                             | Default |
-| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `voiceModel` | string | Model used for voice transcription. Leave empty to keep voice dictation disabled until a voice model is selected. Can also be set via `/model --voice`. | `""`    |
+| Setting      | Type   | Description                                                                                                                                                                                                                                                 | Default |
+| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `voiceModel` | string | Model used for voice transcription and as the audio bridge when a text-only main model receives an audio attachment. Leave empty to keep voice dictation and audio bridging disabled until a voice model is selected. Can also be set via `/model --voice`. | `""`    |
 
 #### modelFallbacks
 

docs/users/features/commands.md

@@ -98,7 +98,7 @@ Commands for managing AI tools and models.
 | → `yolo`              | Auto-approve everything (quick prototyping)                                           | `/approval-mode yolo`                                                                                     |
 | `/model`              | Switch model used in current session                                                  | `/model`, `/model <model-id>` (switch immediately)                                                        |
 | `/model --fast`       | Set a lighter model for prompt suggestions                                            | `/model --fast qwen3-coder-flash`                                                                         |
-| `/model --voice`      | Set the model used for voice transcription                                            | `/model --voice <model-id>`                                                                               |
+| `/model --voice`      | Set the model used for voice transcription and audio bridging                         | `/model --voice <model-id>`                                                                               |
 | `/model --vision`     | Set the vision-bridge model used to transcribe images for a text-only main model      | `/model --vision <model-id>`                                                                              |
 | `/model --compaction` | Set the model used for chat compression                                               | `/model --compaction <model-id>`, `/model --compaction clear`                                             |
 | `/model --image`      | Set an image-only model for the built-in image generation tool                        | `/model --image <model-id>`                                                                               |

packages/cli/src/acp-integration/session/Session.test.ts

@@ -4414,7 +4414,7 @@ describe('Session', () => {
       }
     });
 
-    it('routes ACP audio prompts through the voice bridge for text-only primary models', async () => {
+    it('routes ACP audio prompts through the audio bridge for text-only primary models', async () => {
       mockConfig.getEffectiveInputModalities = vi.fn().mockReturnValue({});
       mockChat.sendMessageStream = vi
         .fn()
@@ -4465,7 +4465,7 @@ describe('Session', () => {
       );
     });
 
-    it('does not run the voice bridge when the primary model supports audio', async () => {
+    it('does not run the audio bridge when the primary model supports audio', async () => {
       mockConfig.getEffectiveInputModalities = vi
         .fn()
         .mockReturnValue({ audio: true });
@@ -4570,7 +4570,7 @@ describe('Session', () => {
       );
     });
 
-    it('rejects oversized ACP audio before decoding for the voice bridge', async () => {
+    it('rejects oversized ACP audio before decoding for the audio bridge', async () => {
       const ENV_KEY = 'QWEN_CODE_MAX_INLINE_MEDIA_BYTES';
       const original = process.env[ENV_KEY];
       process.env[ENV_KEY] = String(20 * 1024 * 1024);
@@ -4610,7 +4610,7 @@ describe('Session', () => {
       );
     });
 
-    it('falls back to text-only parts when voice bridge transcription fails', async () => {
+    it('falls back to text-only parts when audio bridge transcription fails', async () => {
       mockConfig.getEffectiveInputModalities = vi.fn().mockReturnValue({});
       mockChat.sendMessageStream = vi
         .fn()
@@ -5122,6 +5122,59 @@ describe('Session', () => {
       }
     });
 
+    it('preserves unsupported audio @ paths for the audio bridge', async () => {
+      const tempDir = await fs.realpath(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'qwen-acp-audio-')),
+      );
+      const audioPath = path.join(tempDir, 'recording.wav');
+      await fs.writeFile(audioPath, 'audio');
+      mockConfig.getProjectRoot = vi.fn().mockReturnValue(tempDir);
+      mockConfig.getWorkspaceContext = vi.fn().mockReturnValue({
+        isPathWithinWorkspace: (pathSpec: string) =>
+          path.resolve(tempDir, pathSpec).startsWith(`${tempDir}${path.sep}`),
+      });
+      mockConfig.getEffectiveInputModalities = vi.fn().mockReturnValue({});
+      Object.assign(mockSettings.merged as Record<string, unknown>, {
+        voiceModel: 'qwen3-asr-flash',
+      });
+      const readManyFilesSpy = vi
+        .spyOn(core, 'readManyFiles')
+        .mockResolvedValue({
+          contentParts: {
+            inlineData: { mimeType: 'audio/wav', data: 'UklGRg==' },
+          },
+        } as Awaited<ReturnType<typeof core.readManyFiles>>);
+      transcribeVoiceAudioSpy.mockResolvedValue('audio transcript');
+      mockChat.sendMessageStream = vi
+        .fn()
+        .mockResolvedValue(createEmptyStream());
+
+      try {
+        await session.prompt({
+          sessionId: 'test-session-id',
+          prompt: [{ type: 'text', text: `listen to @${audioPath}` }],
+        });
+
+        expect(readManyFilesSpy).toHaveBeenCalledWith(
+          mockConfig,
+          expect.objectContaining({
+            paths: [audioPath],
+            preserveUnsupportedAudioForBridge: true,
+            validatedPathIdentities: expect.any(Map),
+          }),
+        );
+        expect(textParts(firstSentMessage())).toContainEqual(
+          expect.stringContaining('audio transcript'),
+        );
+        expect(firstSentMessage().some((part) => 'inlineData' in part)).toBe(
+          false,
+        );
+      } finally {
+        readManyFilesSpy.mockRestore();
+        await fs.rm(tempDir, { recursive: true, force: true });
+      }
+    });
+
     it('resolves image @ paths from ACP text through the vision bridge', async () => {
       const tempDir = await fs.realpath(
         await fs.mkdtemp(path.join(os.tmpdir(), 'qwen-acp-image-')),
@@ -5185,6 +5238,52 @@ describe('Session', () => {
       }
     });
 
+    it('reads image @ paths for an image-capable primary model without the vision bridge', async () => {
+      const tempDir = await fs.realpath(
+        await fs.mkdtemp(path.join(os.tmpdir(), 'qwen-acp-imgcap-')),
+      );
+      const imagePath = path.join(tempDir, 'shot.png');
+      await fs.writeFile(imagePath, 'image');
+      mockConfig.getProjectRoot = vi.fn().mockReturnValue(tempDir);
+      mockConfig.getWorkspaceContext = vi.fn().mockReturnValue({
+        isPathWithinWorkspace: (pathSpec: string) =>
+          path.resolve(tempDir, pathSpec).startsWith(`${tempDir}${path.sep}`),
+      });
+      mockConfig.getEffectiveInputModalities = vi
+        .fn()
+        .mockReturnValue({ image: true });
+      const readManyFilesSpy = vi
+        .spyOn(core, 'readManyFiles')
+        .mockResolvedValue({
+          contentParts: {
+            inlineData: { mimeType: 'image/png', data: 'iVBORw0KGgo=' },
+          },
+        } as Awaited<ReturnType<typeof core.readManyFiles>>);
+      mockChat.sendMessageStream = vi
+        .fn()
+        .mockResolvedValue(createEmptyStream());
+
+      try {
+        await session.prompt({
+          sessionId: 'test-session-id',
+          prompt: [{ type: 'text', text: `look at @${imagePath}` }],
+        });
+
+        expect(readManyFilesSpy).toHaveBeenCalledWith(
+          mockConfig,
+          expect.objectContaining({
+            paths: [imagePath],
+          }),
+        );
+        expect(firstSentMessage().some((part) => 'inlineData' in part)).toBe(
+          true,
+        );
+      } finally {
+        readManyFilesSpy.mockRestore();
+        await fs.rm(tempDir, { recursive: true, force: true });
+      }
+    });
+
     it('ignores non-image and relative ACP text @ paths', async () => {
       const tempDir = await fs.realpath(
         await fs.mkdtemp(path.join(os.tmpdir(), 'qwen-acp-paths-')),
@@ -7145,7 +7244,7 @@ describe('Session', () => {
         });
 
         const audioFallbackPart = {
-          text: '[Voice bridge could not transcribe attached audio: no voice model is configured. The audio content is unavailable; do not assume or invent what it says.]',
+          text: '[Audio bridge could not transcribe attached audio: no voice model is configured. The audio content is unavailable; do not assume or invent what it says.]',
         };
         const midTurnParts: Part[] = [
           {