feat(cli): select an output style via general.outputStyle or --output-style

docs/users/configuration/settings.md

@@ -80,6 +80,7 @@ Settings are organized into categories. Most settings should be placed within th
 | Setting                                    | Type    | Description                                                                                                                                                                                                                                                                                                               | Default     |
 | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
 | `general.preferredEditor`                  | string  | The preferred editor to open files in.                                                                                                                                                                                                                                                                                    | `undefined` |
+| `general.outputStyle`                      | string  | Name of the output style that shapes how responses are written: `Concise`, `Proactive`, `Explanatory`, or `Learning` (case-insensitive). Leave unset, or set `default`, for the default style. `--output-style` overrides it for one run.                                                                                 | `undefined` |
 | `general.vimMode`                          | boolean | Enable Vim keybindings.                                                                                                                                                                                                                                                                                                   | `false`     |
 | `general.enableAutoUpdate`                 | boolean | Enable automatic update checks and installations on startup.                                                                                                                                                                                                                                                              | `true`      |
 | `general.showSessionRecap`                 | boolean | Auto-show a one-line "where you left off" recap when returning to the terminal after being away. Off by default. Use `/recap` to trigger manually regardless of this setting.                                                                                                                                             | `false`     |

docs/users/features/headless.md

@@ -119,6 +119,19 @@ qwen -p "Summarize this repository" \
   --append-system-prompt "Return exactly three bullets."
 ```
 
+### Choose an Output Style
+
+Use `--output-style` to pick one of the built-in output styles for this run. A style is a named block of instructions layered onto the built-in prompt that changes how the answer is written — `Concise` leads with the result and drops preamble and narration, `Proactive` starts working instead of proposing, `Explanatory` adds short notes about the codebase along the way. It overrides the `general.outputStyle` setting; `default` selects no style.
+
+```bash
+qwen -p "Why does the build fail on Windows?" --output-style Concise
+```
+
+> [!note]
+>
+> - `Learning` asks you to write part of the code and waits for a reply, so it is skipped in headless runs.
+> - An unknown style name prints a warning and the run continues with the default style.
+
 > [!note]
 >
 > - `--system-prompt` applies only to the current run's main session.

packages/cli/src/config/config.test.ts

@@ -575,6 +575,12 @@ describe('parseArguments', () => {
     expect(argv.systemPrompt).toBeUndefined();
   });
 
+  it('should parse --output-style', async () => {
+    process.argv = ['node', 'script.js', '--output-style', 'Concise'];
+    const argv = await parseArguments();
+    expect(argv.outputStyle).toBe('Concise');
+  });
+
   it('should allow -r flag as alias for --resume', async () => {
     process.argv = [
       'node',
@@ -1453,6 +1459,75 @@ describe('loadCliConfig', () => {
     });
   });
 
+  describe('output style', () => {
+    it('leaves the style unset by default', async () => {
+      process.argv = ['node', 'script.js'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig({}, argv);
+      expect(config.getOutputStyle()).toBeUndefined();
+    });
+
+    it('selects a built-in style from general.outputStyle, case-insensitively', async () => {
+      process.argv = ['node', 'script.js'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig(
+        { general: { outputStyle: 'concise' } },
+        argv,
+      );
+      expect(config.getOutputStyle()?.name).toBe('Concise');
+    });
+
+    it('lets --output-style override the setting', async () => {
+      process.argv = ['node', 'script.js', '--output-style', 'Explanatory'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig(
+        { general: { outputStyle: 'Concise' } },
+        argv,
+      );
+      expect(config.getOutputStyle()?.name).toBe('Explanatory');
+    });
+
+    it('treats "default" as no style, even when the setting names one', async () => {
+      process.argv = ['node', 'script.js', '--output-style', 'default'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig(
+        { general: { outputStyle: 'Concise' } },
+        argv,
+      );
+      expect(config.getOutputStyle()).toBeUndefined();
+    });
+
+    it('warns about an unknown style and falls back to the default', async () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      process.argv = ['node', 'script.js'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig(
+        { general: { outputStyle: 'Verbose' } },
+        argv,
+      );
+      expect(config.getOutputStyle()).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Unknown output style "Verbose" (from general.outputStyle)',
+        ),
+      );
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Concise, Proactive, Explanatory, Learning'),
+      );
+    });
+
+    it('names the flag when the unknown style came from --output-style', async () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      process.argv = ['node', 'script.js', '--output-style', 'Verbose'];
+      const argv = await parseArguments();
+      const config = await loadCliConfig({}, argv);
+      expect(config.getOutputStyle()).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('(from --output-style)'),
+      );
+    });
+  });
+
   it('should propagate runtime sleep prevention setting', async () => {
     process.argv = ['node', 'script.js'];
     const argv = await parseArguments();

packages/cli/src/config/config.ts

@@ -46,6 +46,9 @@ import {
   type WebSearchSettings,
   MAX_SUBAGENT_DEPTH_LIMIT,
   addDaemonRequestAttribute,
+  BUILT_IN_OUTPUT_STYLES,
+  getBuiltInOutputStyle,
+  type OutputStyleDefinition,
 } from '@qwen-code/qwen-code-core';
 import { extensionsCommand } from '../commands/extensions.js';
 import { hooksCommand } from '../commands/hooks.js';
@@ -145,6 +148,7 @@ export interface CliArgs {
   promptInteractive: string | undefined;
   systemPrompt: string | undefined;
   appendSystemPrompt: string | undefined;
+  outputStyle: string | undefined;
   yolo: boolean | undefined;
   bare: boolean | undefined;
   safeMode?: boolean | undefined;
@@ -687,6 +691,11 @@ export async function parseArguments(): Promise<CliArgs> {
           description:
             'Append instructions to the main session system prompt for this run. Can be combined with --system-prompt.',
         })
+        .option('output-style', {
+          type: 'string',
+          description:
+            'Output style for this run, for example "Concise" or "Explanatory". Overrides the general.outputStyle setting; "default" selects no style.',
+        })
         .option('sandbox', {
           alias: 's',
           type: 'boolean',
@@ -1497,6 +1506,35 @@ export class SessionIdConflictError extends Error {
   }
 }
 
+/**
+ * Resolves the output style for this session. `--output-style` wins over
+ * `general.outputStyle`; an unset, empty, or `default` value means no style.
+ * An unknown name is reported and the session falls back to the default
+ * style rather than refusing to start, so a typo in settings.json never
+ * locks the user out.
+ */
+export function resolveOutputStyle(
+  argvStyle: string | undefined,
+  settingsStyle: string | undefined,
+): OutputStyleDefinition | undefined {
+  const name = (argvStyle ?? settingsStyle)?.trim();
+  if (!name || name.toLowerCase() === 'default') {
+    return undefined;
+  }
+  const style = getBuiltInOutputStyle(name);
+  if (style) {
+    return style;
+  }
+  const known = BUILT_IN_OUTPUT_STYLES.map((s) => s.name).join(', ');
+  const source =
+    argvStyle !== undefined ? '--output-style' : 'general.outputStyle';
+  const warning = `Unknown output style "${name}" (from ${source}); using the default style. Available styles: ${known}.`;
+  debugLogger.warn(warning);
+  // eslint-disable-next-line no-console
+  console.error(`WARNING: ${warning}`);
+  return undefined;
+}
+
 export async function loadCliConfig(
   settings: Settings,
   argv: CliArgs,
@@ -2160,6 +2198,10 @@ export async function loadCliConfig(
     question,
     systemPrompt: argv.systemPrompt,
     appendSystemPrompt: argv.appendSystemPrompt,
+    outputStyle: resolveOutputStyle(
+      argv.outputStyle,
+      settings.general?.outputStyle,
+    ),
     // Legacy fields – kept for backward compatibility with getCoreTools() etc.
     coreTools:
       bareMode || safeMode

packages/cli/src/config/settingsSchema.ts

@@ -433,6 +433,16 @@ const SETTINGS_SCHEMA = {
         description: 'The preferred editor to open files in.',
         showInDialog: true,
       },
+      outputStyle: {
+        type: 'string',
+        label: 'Output Style',
+        category: 'General',
+        requiresRestart: false,
+        default: undefined as string | undefined,
+        description:
+          'Name of the output style that shapes how responses are written, for example "Concise" or "Explanatory". Leave unset for the default style.',
+        showInDialog: false,
+      },
       vimMode: {
         type: 'boolean',
         label: 'Vim Mode',

packages/cli/src/gemini.test.tsx

@@ -1751,6 +1751,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       promptInteractive: undefined,
       systemPrompt: undefined,
       appendSystemPrompt: undefined,
+      outputStyle: undefined,
       query: undefined,
       yolo: undefined,
       bare: undefined,
@@ -1878,6 +1879,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       promptInteractive: undefined,
       systemPrompt: undefined,
       appendSystemPrompt: undefined,
+      outputStyle: undefined,
       query: undefined,
       yolo: undefined,
       bare: undefined,
@@ -2004,6 +2006,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       promptInteractive: undefined,
       systemPrompt: undefined,
       appendSystemPrompt: undefined,
+      outputStyle: undefined,
       query: undefined,
       yolo: undefined,
       bare: undefined,
@@ -2126,6 +2129,7 @@ describe('gemini.tsx main function kitty protocol', () => {
       promptInteractive: undefined,
       systemPrompt: undefined,
       appendSystemPrompt: undefined,
+      outputStyle: undefined,
       query: undefined,
       yolo: undefined,
       bare: undefined,