feat: update references from Gemini to Qwen in setup commands and gitignore handling

Remove `/quit-confirm` flow

.github/workflows/release-sdk.yml

@@ -0,0 +1,219 @@
+name: 'Release SDK'
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'The version to release (e.g., v0.1.11). Required for manual patch releases.'
+        required: false
+        type: 'string'
+      ref:
+        description: 'The branch or ref (full git sha) to release from.'
+        required: true
+        type: 'string'
+        default: 'main'
+      dry_run:
+        description: 'Run a dry-run of the release process; no branches, npm packages or GitHub releases will be created.'
+        required: true
+        type: 'boolean'
+        default: true
+      create_nightly_release:
+        description: 'Auto apply the nightly release tag, input version is ignored.'
+        required: false
+        type: 'boolean'
+        default: false
+      create_preview_release:
+        description: 'Auto apply the preview release tag, input version is ignored.'
+        required: false
+        type: 'boolean'
+        default: false
+      force_skip_tests:
+        description: 'Select to skip the "Run Tests" step in testing. Prod releases should run tests'
+        required: false
+        type: 'boolean'
+        default: false
+
+jobs:
+  release-sdk:
+    runs-on: 'ubuntu-latest'
+    environment:
+      name: 'production-release'
+      url: '${{ github.server_url }}/${{ github.repository }}/releases/tag/sdk-typescript-${{ steps.version.outputs.RELEASE_TAG }}'
+    if: |-
+      ${{ github.repository == 'QwenLM/qwen-code' }}
+    permissions:
+      contents: 'write'
+      packages: 'write'
+      id-token: 'write'
+      issues: 'write'
+    outputs:
+      RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+
+    steps:
+      - name: 'Checkout'
+        uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # ratchet:actions/checkout@v5
+        with:
+          ref: '${{ github.event.inputs.ref || github.sha }}'
+          fetch-depth: 0
+
+      - name: 'Set booleans for simplified logic'
+        env:
+          CREATE_NIGHTLY_RELEASE: '${{ github.event.inputs.create_nightly_release }}'
+          CREATE_PREVIEW_RELEASE: '${{ github.event.inputs.create_preview_release }}'
+          DRY_RUN_INPUT: '${{ github.event.inputs.dry_run }}'
+        id: 'vars'
+        run: |-
+          is_nightly="false"
+          if [[ "${CREATE_NIGHTLY_RELEASE}" == "true" ]]; then
+            is_nightly="true"
+          fi
+          echo "is_nightly=${is_nightly}" >> "${GITHUB_OUTPUT}"
+
+          is_preview="false"
+          if [[ "${CREATE_PREVIEW_RELEASE}" == "true" ]]; then
+            is_preview="true"
+          fi
+          echo "is_preview=${is_preview}" >> "${GITHUB_OUTPUT}"
+
+          is_dry_run="false"
+          if [[ "${DRY_RUN_INPUT}" == "true" ]]; then
+            is_dry_run="true"
+          fi
+          echo "is_dry_run=${is_dry_run}" >> "${GITHUB_OUTPUT}"
+
+      - name: 'Setup Node.js'
+        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: 'Install Dependencies'
+        run: |-
+          npm ci
+
+      - name: 'Get the version'
+        id: 'version'
+        run: |
+          VERSION_ARGS=()
+          if [[ "${IS_NIGHTLY}" == "true" ]]; then
+            VERSION_ARGS+=(--type=nightly)
+          elif [[ "${IS_PREVIEW}" == "true" ]]; then
+            VERSION_ARGS+=(--type=preview)
+            if [[ -n "${MANUAL_VERSION}" ]]; then
+              VERSION_ARGS+=("--preview_version_override=${MANUAL_VERSION}")
+            fi
+          else
+            VERSION_ARGS+=(--type=stable)
+            if [[ -n "${MANUAL_VERSION}" ]]; then
+              VERSION_ARGS+=("--stable_version_override=${MANUAL_VERSION}")
+            fi
+          fi
+
+          VERSION_JSON=$(node packages/sdk-typescript/scripts/get-release-version.js "${VERSION_ARGS[@]}")
+          echo "RELEASE_TAG=$(echo "$VERSION_JSON" | jq -r .releaseTag)" >> "$GITHUB_OUTPUT"
+          echo "RELEASE_VERSION=$(echo "$VERSION_JSON" | jq -r .releaseVersion)" >> "$GITHUB_OUTPUT"
+          echo "NPM_TAG=$(echo "$VERSION_JSON" | jq -r .npmTag)" >> "$GITHUB_OUTPUT"
+
+          echo "PREVIOUS_RELEASE_TAG=$(echo "$VERSION_JSON" | jq -r .previousReleaseTag)" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          IS_NIGHTLY: '${{ steps.vars.outputs.is_nightly }}'
+          IS_PREVIEW: '${{ steps.vars.outputs.is_preview }}'
+          MANUAL_VERSION: '${{ inputs.version }}'
+
+      - name: 'Run Tests'
+        if: |-
+          ${{ github.event.inputs.force_skip_tests != 'true' }}
+        working-directory: 'packages/sdk-typescript'
+        run: |
+          npm run test:ci
+        env:
+          OPENAI_API_KEY: '${{ secrets.OPENAI_API_KEY }}'
+          OPENAI_BASE_URL: '${{ secrets.OPENAI_BASE_URL }}'
+          OPENAI_MODEL: '${{ secrets.OPENAI_MODEL }}'
+
+      - name: 'Configure Git User'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: 'Create and switch to a release branch'
+        id: 'release_branch'
+        env:
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+        run: |-
+          BRANCH_NAME="release/sdk-typescript/${RELEASE_TAG}"
+          git switch -c "${BRANCH_NAME}"
+          echo "BRANCH_NAME=${BRANCH_NAME}" >> "${GITHUB_OUTPUT}"
+
+      - name: 'Update package version'
+        working-directory: 'packages/sdk-typescript'
+        env:
+          RELEASE_VERSION: '${{ steps.version.outputs.RELEASE_VERSION }}'
+        run: |-
+          npm version "${RELEASE_VERSION}" --no-git-tag-version --allow-same-version
+
+      - name: 'Commit and Conditionally Push package version'
+        env:
+          BRANCH_NAME: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+          IS_DRY_RUN: '${{ steps.vars.outputs.is_dry_run }}'
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+        run: |-
+          git add packages/sdk-typescript/package.json
+          if git diff --staged --quiet; then
+            echo "No version changes to commit"
+          else
+            git commit -m "chore(release): sdk-typescript ${RELEASE_TAG}"
+          fi
+          if [[ "${IS_DRY_RUN}" == "false" ]]; then
+            echo "Pushing release branch to remote..."
+            git push --set-upstream origin "${BRANCH_NAME}" --follow-tags
+          else
+            echo "Dry run enabled. Skipping push."
+          fi
+
+      - name: 'Build SDK'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm run build
+
+      - name: 'Configure npm for publishing'
+        uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' # ratchet:actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@qwen-code'
+
+      - name: 'Publish @qwen-code/sdk-typescript'
+        working-directory: 'packages/sdk-typescript'
+        run: |-
+          npm publish --access public --tag=${{ steps.version.outputs.NPM_TAG }} ${{ steps.vars.outputs.is_dry_run == 'true' && '--dry-run' || '' }}
+        env:
+          NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
+
+      - name: 'Create GitHub Release and Tag'
+        if: |-
+          ${{ steps.vars.outputs.is_dry_run == 'false' }}
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
+          RELEASE_TAG: '${{ steps.version.outputs.RELEASE_TAG }}'
+          PREVIOUS_RELEASE_TAG: '${{ steps.version.outputs.PREVIOUS_RELEASE_TAG }}'
+        run: |-
+          gh release create "sdk-typescript-${RELEASE_TAG}" \
+            --target "$RELEASE_BRANCH" \
+            --title "SDK TypeScript Release ${RELEASE_TAG}" \
+            --notes-start-tag "sdk-typescript-${PREVIOUS_RELEASE_TAG}" \
+            --generate-notes
+
+      - name: 'Create Issue on Failure'
+        if: |-
+          ${{ failure() }}
+        env:
+          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
+          RELEASE_TAG: "${{ steps.version.outputs.RELEASE_TAG || 'N/A' }}"
+          DETAILS_URL: '${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+        run: |-
+          gh issue create \
+            --title "SDK Release Failed for ${RELEASE_TAG} on $(date +'%Y-%m-%d')" \
+            --body "The SDK release workflow failed. See the full run for details: ${DETAILS_URL}"

.vscode/launch.json

@@ -79,7 +79,6 @@
         "--",
         "-p",
         "${input:prompt}",
-        "-y",
         "--output-format",
         "stream-json"
       ],

docs/cli/commands.md

@@ -145,16 +145,6 @@ Slash commands provide meta-level control over the CLI itself.
     - **`nodesc`** or **`nodescriptions`**:
       - **Description:** Hide tool descriptions, showing only the tool names.
 
-- **`/quit-confirm`**
-  - **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session.
-  - **Usage:** `/quit-confirm`
-  - **Features:**
-    - **Quit immediately:** Exit without saving anything (equivalent to `/quit`)
-    - **Generate summary and quit:** Create a project summary using `/summary` before exiting
-    - **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting
-  - **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog
-  - **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits.
-
 - **`/quit`** (or **`/exit`**)
   - **Description:** Exit Qwen Code immediately without any confirmation dialog.
 

docs/cli/configuration-v1.md

@@ -671,4 +671,4 @@ Note: When usage statistics are enabled, events are sent to an Alibaba Cloud RUM
   - **Category:** UI
   - **Requires Restart:** No
   - **Example:** `"enableWelcomeBack": false`
-  - **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command and quit confirmation dialog. See the [Welcome Back documentation](./welcome-back.md) for more details.
+  - **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/summary` command. See the [Welcome Back documentation](./welcome-back.md) for more details.

docs/features/welcome-back.md

@@ -81,14 +81,6 @@ The Welcome Back feature works seamlessly with the `/summary` command:
 2. **Automatic Detection:** Next time you start Qwen Code in this project, Welcome Back will detect the summary
 3. **Resume Work:** Choose to continue and the summary will be loaded as context
 
-### Quit Confirmation
-
-When exiting with `/quit-confirm` and choosing "Generate summary and quit":
-
-1. A project summary is automatically created
-2. Next session will trigger the Welcome Back dialog
-3. You can seamlessly continue your work
-
 ## File Structure
 
 The Welcome Back feature creates and uses:

eslint.config.js

@@ -22,6 +22,7 @@ export default tseslint.config(
       'bundle/**',
       'package/bundle/**',
       '.integration-tests/**',
+      'packages/**/.integration-test/**',
       'dist/**',
     ],
   },
@@ -150,7 +151,7 @@ export default tseslint.config(
     },
   },
   {
-    files: ['packages/*/src/**/*.test.{ts,tsx}'],
+    files: ['packages/*/src/**/*.test.{ts,tsx}', 'packages/**/test/**/*.test.{ts,tsx}'],
     plugins: {
       vitest,
     },
@@ -158,11 +159,19 @@ export default tseslint.config(
       ...vitest.configs.recommended.rules,
       'vitest/expect-expect': 'off',
       'vitest/no-commented-out-tests': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
     },
   },
   // extra settings for scripts that we run directly with node
   {
-    files: ['./scripts/**/*.js', 'esbuild.config.js'],
+    files: ['./scripts/**/*.js', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
     languageOptions: {
       globals: {
         ...globals.node,
@@ -229,7 +238,7 @@ export default tseslint.config(
   prettierConfig,
   // extra settings for scripts that we run directly with node
   {
-    files: ['./integration-tests/**/*.js'],
+    files: ['./integration-tests/**/*.{js,ts,tsx}'],
     languageOptions: {
       globals: {
         ...globals.node,

integration-tests/globalSetup.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2025 Qwen Team
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -30,6 +30,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootDir = join(__dirname, '..');
 const integrationTestsDir = join(rootDir, '.integration-tests');
 let runDir = ''; // Make runDir accessible in teardown
+let sdkE2eRunDir = ''; // SDK E2E test run directory
 
 const memoryFilePath = join(
   os.homedir(),
@@ -48,14 +49,36 @@ export async function setup() {
     // File doesn't exist, which is fine.
   }
 
+  // Setup for CLI integration tests
   runDir = join(integrationTestsDir, `${Date.now()}`);
   await mkdir(runDir, { recursive: true });
 
+  // Setup for SDK E2E tests (separate directory with prefix)
+  sdkE2eRunDir = join(integrationTestsDir, `sdk-e2e-${Date.now()}`);
+  await mkdir(sdkE2eRunDir, { recursive: true });
+
   // Clean up old test runs, but keep the latest few for debugging
   try {
     const testRuns = await readdir(integrationTestsDir);
-    if (testRuns.length > 5) {
-      const oldRuns = testRuns.sort().slice(0, testRuns.length - 5);
+
+    // Clean up old CLI integration test runs (without sdk-e2e- prefix)
+    const cliTestRuns = testRuns.filter((run) => !run.startsWith('sdk-e2e-'));
+    if (cliTestRuns.length > 5) {
+      const oldRuns = cliTestRuns.sort().slice(0, cliTestRuns.length - 5);
+      await Promise.all(
+        oldRuns.map((oldRun) =>
+          rm(join(integrationTestsDir, oldRun), {
+            recursive: true,
+            force: true,
+          }),
+        ),
+      );
+    }
+
+    // Clean up old SDK E2E test runs (with sdk-e2e- prefix)
+    const sdkTestRuns = testRuns.filter((run) => run.startsWith('sdk-e2e-'));
+    if (sdkTestRuns.length > 5) {
+      const oldRuns = sdkTestRuns.sort().slice(0, sdkTestRuns.length - 5);
       await Promise.all(
         oldRuns.map((oldRun) =>
           rm(join(integrationTestsDir, oldRun), {
@@ -69,24 +92,37 @@ export async function setup() {
     console.error('Error cleaning up old test runs:', e);
   }
 
+  // Environment variables for CLI integration tests
   process.env['INTEGRATION_TEST_FILE_DIR'] = runDir;
   process.env['GEMINI_CLI_INTEGRATION_TEST'] = 'true';
   process.env['TELEMETRY_LOG_FILE'] = join(runDir, 'telemetry.log');
 
+  // Environment variables for SDK E2E tests
+  process.env['E2E_TEST_FILE_DIR'] = sdkE2eRunDir;
+  process.env['TEST_CLI_PATH'] = join(rootDir, 'dist/cli.js');
+
   if (process.env['KEEP_OUTPUT']) {
     console.log(`Keeping output for test run in: ${runDir}`);
+    console.log(`Keeping output for SDK E2E test run in: ${sdkE2eRunDir}`);
   }
   process.env['VERBOSE'] = process.env['VERBOSE'] ?? 'false';
 
   console.log(`\nIntegration test output directory: ${runDir}`);
+  console.log(`SDK E2E test output directory: ${sdkE2eRunDir}`);
+  console.log(`CLI path: ${process.env['TEST_CLI_PATH']}`);
 }
 
 export async function teardown() {
-  // Cleanup the test run directory unless KEEP_OUTPUT is set
+  // Cleanup the CLI test run directory unless KEEP_OUTPUT is set
   if (process.env['KEEP_OUTPUT'] !== 'true' && runDir) {
     await rm(runDir, { recursive: true, force: true });
   }
 
+  // Cleanup the SDK E2E test run directory unless KEEP_OUTPUT is set
+  if (process.env['KEEP_OUTPUT'] !== 'true' && sdkE2eRunDir) {
+    await rm(sdkE2eRunDir, { recursive: true, force: true });
+  }
+
   if (originalMemoryContent !== null) {
     await mkdir(dirname(memoryFilePath), { recursive: true });
     await writeFile(memoryFilePath, originalMemoryContent, 'utf-8');

integration-tests/sdk-typescript/abort-and-lifecycle.test.ts

@@ -0,0 +1,486 @@
+/**
+ * E2E tests based on abort-and-lifecycle.ts example
+ * Tests AbortController integration and process lifecycle management
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  AbortError,
+  isAbortError,
+  isSDKAssistantMessage,
+  type TextBlock,
+  type ContentBlock,
+} from '@qwen-code/sdk-typescript';
+import { SDKTestHelper, createSharedTestOptions } from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('AbortController and Process Lifecycle (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('abort-and-lifecycle');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+  describe('Basic AbortController Usage', () => {
+    it('should support AbortController cancellation', async () => {
+      const controller = new AbortController();
+
+      // Abort after 5 seconds
+      setTimeout(() => {
+        controller.abort();
+      }, 5000);
+
+      const q = query({
+        prompt: 'Write a very long story about TypeScript programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 100);
+
+            // Should receive some content before abort
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+
+        // Should not reach here - query should be aborted
+        expect(false).toBe(true);
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle abort during query execution', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      let receivedFirstMessage = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            if (!receivedFirstMessage) {
+              // Abort immediately after receiving first assistant message
+              receivedFirstMessage = true;
+              controller.abort();
+            }
+          }
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+        // Should have received at least one message before abort
+        expect(receivedFirstMessage).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle abort immediately after query starts', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Write a very long essay',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort immediately after query initialization
+      setTimeout(() => {
+        controller.abort();
+      }, 200);
+
+      try {
+        for await (const _message of q) {
+          // May or may not receive messages before abort
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Process Lifecycle Monitoring', () => {
+    it('should handle normal process completion', async () => {
+      const q = query({
+        prompt: 'Why do we choose to go to the moon?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let completedSuccessfully = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 100);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+
+        completedSuccessfully = true;
+      } catch (error) {
+        // Should not throw for normal completion
+        expect(false).toBe(true);
+      } finally {
+        await q.close();
+        expect(completedSuccessfully).toBe(true);
+      }
+    });
+
+    it('should handle process cleanup after error', async () => {
+      const q = query({
+        prompt: 'Hello world',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 50);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+      } catch (error) {
+        // Expected to potentially have errors
+      } finally {
+        // Should cleanup successfully even after error
+        await q.close();
+        expect(true).toBe(true); // Cleanup completed
+      }
+    });
+  });
+
+  describe('Input Stream Control', () => {
+    it('should support endInput() method', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let receivedResponse = false;
+      let endInputCalled = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message) && !endInputCalled) {
+            const textBlocks = message.message.content.filter(
+              (block: ContentBlock): block is TextBlock =>
+                block.type === 'text',
+            );
+            const text = textBlocks.map((b: TextBlock) => b.text).join('');
+
+            expect(text.length).toBeGreaterThan(0);
+            receivedResponse = true;
+
+            // End input after receiving first response
+            q.endInput();
+            endInputCalled = true;
+          }
+        }
+
+        expect(receivedResponse).toBe(true);
+        expect(endInputCalled).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling and Recovery', () => {
+    it('should handle invalid executable path', async () => {
+      try {
+        const q = query({
+          prompt: 'Hello world',
+          options: {
+            pathToQwenExecutable: '/nonexistent/path/to/cli',
+            debug: false,
+          },
+        });
+
+        // Should not reach here - query() should throw immediately
+        for await (const _message of q) {
+          // Should not reach here
+        }
+
+        // Should not reach here
+        expect(false).toBe(true);
+      } catch (error) {
+        expect(error instanceof Error).toBe(true);
+        expect((error as Error).message).toBeDefined();
+        expect((error as Error).message).toContain(
+          'Invalid pathToQwenExecutable',
+        );
+      }
+    });
+
+    it('should throw AbortError with correct properties', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Explain the concept of async programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort after allowing query to start
+      setTimeout(() => controller.abort(), 1000);
+
+      try {
+        for await (const _message of q) {
+          // May receive some messages before abort
+        }
+      } catch (error) {
+        // Verify error type and helper functions
+        expect(isAbortError(error)).toBe(true);
+        expect(error instanceof AbortError).toBe(true);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBeDefined();
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Debugging with stderr callback', () => {
+    it('should capture stderr messages when debug is enabled', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Why do we choose to go to the moon?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            const textBlocks = message.message.content.filter(
+              (block): block is TextBlock => block.type === 'text',
+            );
+            const text = textBlocks
+              .map((b) => b.text)
+              .join('')
+              .slice(0, 50);
+            expect(text.length).toBeGreaterThan(0);
+          }
+        }
+      } finally {
+        await q.close();
+        expect(stderrMessages.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('should not capture stderr when debug is disabled', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const _message of q) {
+          // Consume all messages
+        }
+      } finally {
+        await q.close();
+        // Should have minimal or no stderr output when debug is false
+        expect(stderrMessages.length).toBeLessThan(10);
+      }
+    });
+  });
+
+  describe('Abort with Cleanup', () => {
+    it('should cleanup properly after abort', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Write a very long essay about programming',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Abort immediately
+      setTimeout(() => controller.abort(), 100);
+
+      try {
+        for await (const _message of q) {
+          // May receive some messages before abort
+        }
+      } catch (error) {
+        if (error instanceof AbortError) {
+          expect(true).toBe(true); // Expected abort error
+        } else {
+          throw error; // Unexpected error
+        }
+      } finally {
+        await q.close();
+        expect(true).toBe(true); // Cleanup completed after abort
+      }
+    });
+
+    it('should handle multiple abort calls gracefully', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Count to 100',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Multiple abort calls
+      setTimeout(() => controller.abort(), 100);
+      setTimeout(() => controller.abort(), 200);
+      setTimeout(() => controller.abort(), 300);
+
+      try {
+        for await (const _message of q) {
+          // Should be interrupted
+        }
+      } catch (error) {
+        expect(isAbortError(error)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Resource Management Edge Cases', () => {
+    it('should handle close() called multiple times', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      // Start the query
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+
+      // Close multiple times
+      await q.close();
+      await q.close();
+      await q.close();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+
+    it('should handle abort after close', async () => {
+      const controller = new AbortController();
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          abortController: controller,
+          debug: false,
+        },
+      });
+
+      // Start and close immediately
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+      await q.close();
+
+      // Abort after close
+      controller.abort();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+  });
+});

integration-tests/sdk-typescript/configuration-options.test.ts

@@ -0,0 +1,641 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for SDK configuration options:
+ * - logLevel: Controls SDK internal logging verbosity
+ * - env: Environment variables passed to CLI process
+ * - authType: Authentication type for AI service
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  type SDKMessage,
+} from '@qwen-code/sdk-typescript';
+import {
+  SDKTestHelper,
+  extractText,
+  createSharedTestOptions,
+  assertSuccessfulCompletion,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('Configuration Options (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('configuration-options');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('logLevel Option', () => {
+    it('should respect logLevel: debug and capture detailed logs', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 1 + 1? Just answer the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'debug',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Debug level should produce verbose logging
+        expect(stderrMessages.length).toBeGreaterThan(0);
+
+        // Debug logs should contain detailed information like [DEBUG]
+        const hasDebugLogs = stderrMessages.some(
+          (msg) => msg.includes('[DEBUG]') || msg.includes('debug'),
+        );
+        expect(hasDebugLogs).toBe(true);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: info and filter out debug messages', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 2 + 2? Just answer the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'info',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Info level should filter out debug messages
+        // Check that we don't have [DEBUG] level messages from the SDK logger
+        const sdkDebugLogs = stderrMessages.filter(
+          (msg) =>
+            msg.includes('[DEBUG]') && msg.includes('[ProcessTransport]'),
+        );
+        expect(sdkDebugLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: warn and only show warnings and errors', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'warn',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Warn level should filter out info and debug messages from SDK
+        const sdkInfoOrDebugLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') || msg.includes('[INFO]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkInfoOrDebugLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect logLevel: error and only show error messages', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello world',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'error',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Error level should filter out all non-error messages from SDK
+        const sdkNonErrorLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') ||
+              msg.includes('[INFO]') ||
+              msg.includes('[WARN]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkNonErrorLogs.length).toBe(0);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use logLevel over debug flag when both are provided', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 3 + 3?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true, // Would normally enable debug logging
+          logLevel: 'error', // But logLevel should take precedence
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const _message of q) {
+          // Consume all messages
+        }
+
+        // logLevel: error should suppress debug/info/warn even with debug: true
+        const sdkNonErrorLogs = stderrMessages.filter(
+          (msg) =>
+            (msg.includes('[DEBUG]') ||
+              msg.includes('[INFO]') ||
+              msg.includes('[WARN]')) &&
+            (msg.includes('[ProcessTransport]') ||
+              msg.includes('[createQuery]') ||
+              msg.includes('[Query]')),
+        );
+        expect(sdkNonErrorLogs.length).toBe(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('env Option', () => {
+    it('should pass custom environment variables to CLI process', async () => {
+      const q = query({
+        prompt: 'What is 1 + 1? Just the number please.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            CUSTOM_TEST_VAR: 'test_value_12345',
+            ANOTHER_VAR: 'another_value',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // The query should complete successfully with custom env vars
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should allow overriding existing environment variables', async () => {
+      // Store original value for comparison
+      const originalPath = process.env['PATH'];
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            // Override an existing env var (not PATH as it might break things)
+            MY_TEST_OVERRIDE: 'overridden_value',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete successfully
+        assertSuccessfulCompletion(messages);
+
+        // Verify original process env is not modified
+        expect(process.env['PATH']).toBe(originalPath);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should work with empty env object', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {},
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should support setting model-related environment variables', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            // Common model-related env vars that CLI might respect
+            OPENAI_API_KEY: process.env['OPENAI_API_KEY'] || 'test-key',
+          },
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should complete (may succeed or fail based on API key validity)
+        expect(messages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should not leak env vars between query instances', async () => {
+      // First query with specific env var
+      const q1 = query({
+        prompt: 'Say one',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            ISOLATED_VAR_1: 'value_1',
+          },
+          debug: false,
+        },
+      });
+
+      try {
+        for await (const _message of q1) {
+          // Consume messages
+        }
+      } finally {
+        await q1.close();
+      }
+
+      // Second query with different env var
+      const q2 = query({
+        prompt: 'Say two',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          env: {
+            ISOLATED_VAR_2: 'value_2',
+          },
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q2) {
+          messages.push(message);
+        }
+
+        // Second query should complete successfully
+        assertSuccessfulCompletion(messages);
+
+        // Verify process.env is not polluted by either query
+        expect(process.env['ISOLATED_VAR_1']).toBeUndefined();
+        expect(process.env['ISOLATED_VAR_2']).toBeUndefined();
+      } finally {
+        await q2.close();
+      }
+    });
+  });
+
+  describe('authType Option', () => {
+    it('should accept authType: openai', async () => {
+      const q = query({
+        prompt: 'What is 1 + 1? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'openai',
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete with openai auth type
+        assertSuccessfulCompletion(messages);
+
+        // Verify we got an assistant response
+        const assistantMessages = messages.filter(isSDKAssistantMessage);
+        expect(assistantMessages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    // Skip in containerized sandbox environments - qwen-oauth requires user interaction
+    // which is not possible in Docker/Podman CI environments
+    it.skipIf(
+      process.env['SANDBOX'] === 'sandbox:docker' ||
+        process.env['SANDBOX'] === 'sandbox:podman',
+    )('should accept authType: qwen-oauth', async () => {
+      // Note: qwen-oauth requires credentials in ~/.qwen and user interaction
+      // Without credentials, the auth process will timeout waiting for user
+      // This test verifies the option is accepted and passed correctly to CLI
+
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'qwen-oauth',
+          debug: true,
+          logLevel: 'debug',
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        // Use a timeout to avoid hanging when credentials are not configured
+        const timeoutPromise = new Promise<'timeout'>((resolve) =>
+          setTimeout(() => resolve('timeout'), 20000),
+        );
+
+        const collectMessages = async () => {
+          for await (const message of q) {
+            messages.push(message);
+          }
+          return 'completed';
+        };
+
+        const result = await Promise.race([collectMessages(), timeoutPromise]);
+
+        if (result === 'timeout') {
+          // Timeout is expected when OAuth credentials are not configured
+          // Verify that CLI was spawned with correct --auth-type argument
+          const hasAuthTypeArg = stderrMessages.some((msg) =>
+            msg.includes('--auth-type'),
+          );
+          expect(hasAuthTypeArg).toBe(true);
+        } else {
+          // If credentials exist and auth completed, verify we got messages
+          expect(messages.length).toBeGreaterThan(0);
+        }
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use default auth when authType is not specified', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          // authType not specified - should use default
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Query should complete with default auth
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should properly pass authType to CLI process', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Say hi',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          authType: 'openai',
+          debug: true,
+          logLevel: 'debug',
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // There should be spawn log containing auth-type
+        const hasAuthTypeArg = stderrMessages.some((msg) =>
+          msg.includes('--auth-type'),
+        );
+        expect(hasAuthTypeArg).toBe(true);
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Combined Options', () => {
+    it('should work with logLevel, env, and authType together', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'What is 3 + 3? Just the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'debug',
+          env: {
+            COMBINED_TEST_VAR: 'combined_value',
+          },
+          authType: 'openai',
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // All three options should work together
+        expect(stderrMessages.length).toBeGreaterThan(0); // logLevel: debug produces logs
+        expect(assistantText).toMatch(/6/); // Query should work
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain system message consistency with all options', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          logLevel: 'info',
+          env: {
+            SYSTEM_MSG_TEST: 'test',
+          },
+          authType: 'openai',
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should have system init message
+        const systemMessages = messages.filter(isSDKSystemMessage);
+        const initMessage = systemMessages.find((m) => m.subtype === 'init');
+
+        expect(initMessage).toBeDefined();
+        expect(initMessage!.session_id).toBeDefined();
+        expect(initMessage!.tools).toBeDefined();
+        expect(initMessage!.permission_mode).toBeDefined();
+
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/mcp-server.test.ts

@@ -0,0 +1,405 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for MCP (Model Context Protocol) server integration via SDK
+ * Tests that the SDK can properly interact with MCP servers configured in qwen-code
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKResultMessage,
+  isSDKSystemMessage,
+  isSDKUserMessage,
+  type SDKMessage,
+  type ToolUseBlock,
+  type SDKSystemMessage,
+} from '@qwen-code/sdk-typescript';
+import {
+  SDKTestHelper,
+  createMCPServer,
+  extractText,
+  findToolUseBlocks,
+  createSharedTestOptions,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = {
+  ...createSharedTestOptions(),
+  permissionMode: 'yolo' as const,
+};
+
+describe('MCP Server Integration (E2E)', () => {
+  let helper: SDKTestHelper;
+  let serverScriptPath: string;
+  let testDir: string;
+
+  beforeEach(async () => {
+    // Create isolated test environment using SDKTestHelper
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('mcp-server-integration');
+
+    // Create MCP server using the helper utility
+    const mcpServer = await createMCPServer(helper, 'math', 'test-math-server');
+    serverScriptPath = mcpServer.scriptPath;
+  });
+
+  afterEach(async () => {
+    // Cleanup test directory
+    await helper.cleanup();
+  });
+
+  describe('Basic MCP Tool Usage', () => {
+    it('should use MCP add tool to add two numbers', async () => {
+      const q = query({
+        prompt:
+          'Use the add tool to calculate 5 + 10. Just give me the result.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      let foundToolUse = false;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'add');
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+            }
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate tool was called
+        expect(foundToolUse).toBe(true);
+
+        // Validate result contains expected answer
+        expect(assistantText).toMatch(/15/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+        if (isSDKResultMessage(lastMessage)) {
+          expect(lastMessage.subtype).toBe('success');
+        }
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should use MCP multiply tool to multiply two numbers', async () => {
+      const q = query({
+        prompt:
+          'Use the multiply tool to calculate 6 * 7. Just give me the result.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      let foundToolUse = false;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'multiply');
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+            }
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate tool was called
+        expect(foundToolUse).toBe(true);
+
+        // Validate result contains expected answer
+        expect(assistantText).toMatch(/42/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('MCP Server Discovery', () => {
+    it('should list MCP servers in system init message', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      let systemMessage: SDKSystemMessage | null = null;
+
+      try {
+        for await (const message of q) {
+          if (isSDKSystemMessage(message) && message.subtype === 'init') {
+            systemMessage = message;
+            break;
+          }
+        }
+
+        // Validate MCP server is listed
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.mcp_servers).toBeDefined();
+        expect(Array.isArray(systemMessage!.mcp_servers)).toBe(true);
+
+        // Find our test server
+        const testServer = systemMessage!.mcp_servers?.find(
+          (server) => server.name === 'test-math-server',
+        );
+        expect(testServer).toBeDefined();
+
+        // Note: tools are not exposed in the mcp_servers array in system message
+        // They are available through the MCP protocol but not in the init message
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Complex MCP Operations', () => {
+    it('should chain multiple MCP tool calls', async () => {
+      const q = query({
+        prompt:
+          'First use add to calculate 10 + 5, then multiply the result by 2. Give me the final answer.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      const toolCalls: string[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message);
+            toolUseBlocks.forEach((block) => {
+              toolCalls.push(block.name);
+            });
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate both tools were called
+        expect(toolCalls).toContain('add');
+        expect(toolCalls).toContain('multiply');
+
+        // Validate result: (10 + 5) * 2 = 30
+        expect(assistantText).toMatch(/30/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle multiple calls to the same MCP tool', async () => {
+      const q = query({
+        prompt:
+          'Use the add tool twice: first add 1 + 2, then add 3 + 4. Tell me both results.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+      const addToolCalls: ToolUseBlock[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message, 'add');
+            addToolCalls.push(...toolUseBlocks);
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate add tool was called at least twice
+        expect(addToolCalls.length).toBeGreaterThanOrEqual(2);
+
+        // Validate results contain expected answers: 3 and 7
+        expect(assistantText).toMatch(/3/);
+        expect(assistantText).toMatch(/7/);
+
+        // Validate successful completion
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('MCP Tool Message Flow', () => {
+    it('should receive proper message sequence for MCP tool usage', async () => {
+      const q = query({
+        prompt: 'Use add to calculate 2 + 3',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messageTypes: string[] = [];
+      let foundToolUse = false;
+      let foundToolResult = false;
+
+      try {
+        for await (const message of q) {
+          messageTypes.push(message.type);
+
+          if (isSDKAssistantMessage(message)) {
+            const toolUseBlocks = findToolUseBlocks(message);
+            if (toolUseBlocks.length > 0) {
+              foundToolUse = true;
+              expect(toolUseBlocks[0].name).toBe('add');
+              expect(toolUseBlocks[0].input).toBeDefined();
+            }
+          }
+
+          if (isSDKUserMessage(message)) {
+            const content = message.message.content;
+            const contentArray = Array.isArray(content)
+              ? content
+              : [{ type: 'text', text: content }];
+            const toolResultBlock = contentArray.find(
+              (block) => block.type === 'tool_result',
+            );
+            if (toolResultBlock) {
+              foundToolResult = true;
+            }
+          }
+        }
+
+        // Validate message flow
+        expect(foundToolUse).toBe(true);
+        expect(foundToolResult).toBe(true);
+        expect(messageTypes).toContain('system');
+        expect(messageTypes).toContain('assistant');
+        expect(messageTypes).toContain('user');
+        expect(messageTypes).toContain('result');
+
+        // Result should be last message
+        expect(messageTypes[messageTypes.length - 1]).toBe('result');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle gracefully when MCP tool is not available', async () => {
+      const q = query({
+        prompt: 'Use the subtract tool to calculate 10 - 5',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+          mcpServers: {
+            'test-math-server': {
+              command: 'node',
+              args: [serverScriptPath],
+            },
+          },
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Should complete without crashing
+        const lastMessage = messages[messages.length - 1];
+        expect(isSDKResultMessage(lastMessage)).toBe(true);
+
+        // Assistant should indicate tool is not available or provide alternative
+        expect(assistantText.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/multi-turn.test.ts

@@ -0,0 +1,559 @@
+/**
+ * E2E tests based on multi-turn.ts example
+ * Tests multi-turn conversation functionality with real CLI
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKUserMessage,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+  isControlRequest,
+  isControlResponse,
+  isControlCancel,
+  type SDKUserMessage,
+  type SDKAssistantMessage,
+  type TextBlock,
+  type ContentBlock,
+  type SDKMessage,
+  type ControlMessage,
+  type ToolUseBlock,
+} from '@qwen-code/sdk-typescript';
+import { SDKTestHelper, createSharedTestOptions } from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+/**
+ * Determine the message type using protocol type guards
+ */
+function getMessageType(message: SDKMessage | ControlMessage): string {
+  if (isSDKUserMessage(message)) {
+    return '🧑 USER';
+  } else if (isSDKAssistantMessage(message)) {
+    return '🤖 ASSISTANT';
+  } else if (isSDKSystemMessage(message)) {
+    return `🖥️ SYSTEM(${message.subtype})`;
+  } else if (isSDKResultMessage(message)) {
+    return `✅ RESULT(${message.subtype})`;
+  } else if (isSDKPartialAssistantMessage(message)) {
+    return '⏳ STREAM_EVENT';
+  } else if (isControlRequest(message)) {
+    return `🎮 CONTROL_REQUEST(${message.request.subtype})`;
+  } else if (isControlResponse(message)) {
+    return `📭 CONTROL_RESPONSE(${message.response.subtype})`;
+  } else if (isControlCancel(message)) {
+    return '🛑 CONTROL_CANCEL';
+  } else {
+    return '❓ UNKNOWN';
+  }
+}
+
+/**
+ * Helper to extract text from ContentBlock array
+ */
+function extractText(content: ContentBlock[]): string {
+  return content
+    .filter((block): block is TextBlock => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+}
+
+describe('Multi-Turn Conversations (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('multi-turn');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('AsyncIterable Prompt Support', () => {
+    it('should handle multi-turn conversation using AsyncIterable prompt', async () => {
+      // Create multi-turn conversation generator
+      async function* createMultiTurnConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 3 + 3?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      // Create multi-turn query using AsyncIterable prompt
+      const q = query({
+        prompt: createMultiTurnConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      const assistantMessages: SDKAssistantMessage[] = [];
+      const assistantTexts: string[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+            const text = extractText(message.message.content);
+            assistantTexts.push(text);
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(3);
+
+        // Validate content of responses
+        expect(assistantTexts[0]).toMatch(/2/);
+        expect(assistantTexts[1]).toMatch(/4/);
+        expect(assistantTexts[2]).toMatch(/6/);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain session context across turns', async () => {
+      async function* createContextualConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content:
+              'Suppose we have 3 rabbits and 4 carrots. How many animals are there?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'How many animals are there? Only output the number',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createContextualConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+          }
+        }
+
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+
+        // The second response should reference the color blue
+        const secondResponse = extractText(
+          assistantMessages[1].message.content,
+        );
+        expect(secondResponse.toLowerCase()).toContain('3');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Tool Usage in Multi-Turn', () => {
+    it('should handle tool usage across multiple turns', async () => {
+      async function* createToolConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Create a file named test.txt with content "hello"',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Now read the test.txt file',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createToolConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          permissionMode: 'yolo',
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let toolUseCount = 0;
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+            const hasToolUseBlock = message.message.content.some(
+              (block: ContentBlock): block is ToolUseBlock =>
+                block.type === 'tool_use',
+            );
+            if (hasToolUseBlock) {
+              toolUseCount++;
+            }
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(toolUseCount).toBeGreaterThan(0);
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+
+        // Validate second response mentions the file content
+        const secondResponse = extractText(
+          assistantMessages[assistantMessages.length - 1].message.content,
+        );
+        expect(secondResponse.toLowerCase()).toMatch(/hello|test\.txt/);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Message Flow and Sequencing', () => {
+    it('should process messages in correct sequence', async () => {
+      async function* createSequentialConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'First question: What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Second question: What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createSequentialConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messageSequence: string[] = [];
+      const assistantResponses: string[] = [];
+
+      try {
+        for await (const message of q) {
+          const messageType = getMessageType(message);
+          messageSequence.push(messageType);
+
+          if (isSDKAssistantMessage(message)) {
+            const text = extractText(message.message.content);
+            assistantResponses.push(text);
+          }
+        }
+
+        expect(messageSequence.length).toBeGreaterThan(0);
+        expect(assistantResponses.length).toBeGreaterThanOrEqual(2);
+
+        // Should end with result
+        expect(messageSequence[messageSequence.length - 1]).toContain('RESULT');
+
+        // Should have assistant responses
+        expect(messageSequence.some((type) => type.includes('ASSISTANT'))).toBe(
+          true,
+        );
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle conversation completion correctly', async () => {
+      async function* createSimpleConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Hello',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Goodbye',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createSimpleConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let completedNaturally = false;
+      let messageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messageCount++;
+
+          if (isSDKResultMessage(message)) {
+            completedNaturally = true;
+            expect(message.subtype).toBe('success');
+          }
+        }
+
+        expect(messageCount).toBeGreaterThan(0);
+        expect(completedNaturally).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling in Multi-Turn', () => {
+    it('should handle empty conversation gracefully', async () => {
+      async function* createEmptyConversation(): AsyncIterable<SDKUserMessage> {
+        // Generator that yields nothing
+        /* eslint-disable no-constant-condition */
+        if (false) {
+          yield {} as SDKUserMessage; // Unreachable, but satisfies TypeScript
+        }
+      }
+
+      const q = query({
+        prompt: createEmptyConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should handle empty conversation without crashing
+        expect(true).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle conversation with delays', async () => {
+      async function* createDelayedConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'First message',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        // Longer delay to test patience
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'Second message after delay',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createDelayedConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const assistantMessages: SDKAssistantMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            assistantMessages.push(message);
+          }
+        }
+
+        expect(assistantMessages.length).toBeGreaterThanOrEqual(2);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Partial Messages in Multi-Turn', () => {
+    it('should receive partial messages when includePartialMessages is enabled', async () => {
+      async function* createMultiTurnConversation(): AsyncIterable<SDKUserMessage> {
+        const sessionId = crypto.randomUUID();
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 1 + 1?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: {
+            role: 'user',
+            content: 'What is 2 + 2?',
+          },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      }
+
+      const q = query({
+        prompt: createMultiTurnConversation(),
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          includePartialMessages: true,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let partialMessageCount = 0;
+      let assistantMessageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKPartialAssistantMessage(message)) {
+            partialMessageCount++;
+          }
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessageCount++;
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(partialMessageCount).toBeGreaterThan(0);
+        expect(assistantMessageCount).toBeGreaterThanOrEqual(2);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/single-turn.test.ts

@@ -0,0 +1,529 @@
+/**
+ * E2E tests for single-turn query execution
+ * Tests basic query patterns with simple prompts and clear output expectations
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+  type SDKMessage,
+  type SDKSystemMessage,
+  type SDKAssistantMessage,
+} from '@qwen-code/sdk-typescript';
+import {
+  SDKTestHelper,
+  extractText,
+  createSharedTestOptions,
+  assertSuccessfulCompletion,
+  collectMessagesByType,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('Single-Turn Query (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('single-turn');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+  describe('Simple Text Queries', () => {
+    it('should answer basic arithmetic question', async () => {
+      const q = query({
+        prompt: 'What is 2 + 2? Just give me the number.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true,
+          logLevel: 'debug',
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate we got messages
+        expect(messages.length).toBeGreaterThan(0);
+
+        // Validate assistant response content
+        expect(assistantText.length).toBeGreaterThan(0);
+        expect(assistantText).toMatch(/4/);
+
+        // Validate message flow ends with success
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should answer simple factual question', async () => {
+      const q = query({
+        prompt: 'What is the capital of France? One word answer.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate content
+        expect(assistantText.length).toBeGreaterThan(0);
+        expect(assistantText.toLowerCase()).toContain('paris');
+
+        // Validate completion
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle greeting and self-description', async () => {
+      const q = query({
+        prompt: 'Say hello and tell me your name in one sentence.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate content contains greeting
+        expect(assistantText.length).toBeGreaterThan(0);
+        expect(assistantText.toLowerCase()).toMatch(/hello|hi|greetings/);
+
+        // Validate message types
+        const assistantMessages = collectMessagesByType(
+          messages,
+          isSDKAssistantMessage,
+        );
+        expect(assistantMessages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('System Initialization', () => {
+    it('should receive system message with initialization info', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let systemMessage: SDKSystemMessage | null = null;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKSystemMessage(message) && message.subtype === 'init') {
+            systemMessage = message;
+          }
+        }
+
+        // Validate system message exists and has required fields
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.type).toBe('system');
+        expect(systemMessage!.subtype).toBe('init');
+        expect(systemMessage!.uuid).toBeDefined();
+        expect(systemMessage!.session_id).toBeDefined();
+        expect(systemMessage!.cwd).toBeDefined();
+        expect(systemMessage!.tools).toBeDefined();
+        expect(Array.isArray(systemMessage!.tools)).toBe(true);
+        expect(systemMessage!.mcp_servers).toBeDefined();
+        expect(Array.isArray(systemMessage!.mcp_servers)).toBe(true);
+        expect(systemMessage!.model).toBeDefined();
+        expect(systemMessage!.permission_mode).toBeDefined();
+        expect(systemMessage!.qwen_code_version).toBeDefined();
+
+        // Validate system message appears early in sequence
+        const systemMessageIndex = messages.findIndex(
+          (msg) => isSDKSystemMessage(msg) && msg.subtype === 'init',
+        );
+        expect(systemMessageIndex).toBeGreaterThanOrEqual(0);
+        expect(systemMessageIndex).toBeLessThan(3);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain session ID consistency', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let systemMessage: SDKSystemMessage | null = null;
+      const sessionId = q.getSessionId();
+
+      try {
+        for await (const message of q) {
+          if (isSDKSystemMessage(message) && message.subtype === 'init') {
+            systemMessage = message;
+          }
+        }
+
+        // Validate session IDs are consistent
+        expect(sessionId).toBeDefined();
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.session_id).toBeDefined();
+        expect(systemMessage!.uuid).toBeDefined();
+        expect(systemMessage!.session_id).toBe(systemMessage!.uuid);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Message Flow', () => {
+    it('should follow expected message sequence', async () => {
+      const q = query({
+        prompt: 'Say hi',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messageTypes: string[] = [];
+
+      try {
+        for await (const message of q) {
+          messageTypes.push(message.type);
+        }
+
+        // Validate message sequence
+        expect(messageTypes.length).toBeGreaterThan(0);
+        expect(messageTypes).toContain('assistant');
+        expect(messageTypes[messageTypes.length - 1]).toBe('result');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should complete iteration naturally', async () => {
+      const q = query({
+        prompt: 'Say goodbye',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let completedNaturally = false;
+      let messageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messageCount++;
+
+          if (isSDKResultMessage(message)) {
+            completedNaturally = true;
+            expect(message.subtype).toBe('success');
+          }
+        }
+
+        expect(messageCount).toBeGreaterThan(0);
+        expect(completedNaturally).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Configuration Options', () => {
+    it('should respect debug option and capture stderr', async () => {
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+        },
+      });
+
+      try {
+        for await (const _message of q) {
+          // Consume all messages
+        }
+
+        // Debug mode should produce stderr output
+        expect(stderrMessages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should respect cwd option', async () => {
+      const q = query({
+        prompt: 'What is 1 + 1?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let hasResponse = false;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            hasResponse = true;
+          }
+        }
+
+        expect(hasResponse).toBe(true);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should receive partial messages when includePartialMessages is enabled', async () => {
+      const q = query({
+        prompt: 'Count from 1 to 5',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          includePartialMessages: true,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let partialMessageCount = 0;
+      let assistantMessageCount = 0;
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKPartialAssistantMessage(message)) {
+            partialMessageCount++;
+          }
+
+          if (isSDKAssistantMessage(message)) {
+            assistantMessageCount++;
+          }
+        }
+
+        expect(messages.length).toBeGreaterThan(0);
+        expect(partialMessageCount).toBeGreaterThan(0);
+        expect(assistantMessageCount).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Message Type Recognition', () => {
+    it('should correctly identify all message types', async () => {
+      const q = query({
+        prompt: 'What is 5 + 5?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate type guards work correctly
+        const assistantMessages = collectMessagesByType(
+          messages,
+          isSDKAssistantMessage,
+        );
+        const resultMessages = collectMessagesByType(
+          messages,
+          isSDKResultMessage,
+        );
+        const systemMessages = collectMessagesByType(
+          messages,
+          isSDKSystemMessage,
+        );
+
+        expect(assistantMessages.length).toBeGreaterThan(0);
+        expect(resultMessages.length).toBeGreaterThan(0);
+        expect(systemMessages.length).toBeGreaterThan(0);
+
+        // Validate assistant message structure
+        const firstAssistant = assistantMessages[0];
+        expect(firstAssistant.message.content).toBeDefined();
+        expect(Array.isArray(firstAssistant.message.content)).toBe(true);
+
+        // Validate result message structure
+        const resultMessage = resultMessages[0];
+        expect(resultMessage.subtype).toBe('success');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should extract text content from assistant messages', async () => {
+      const q = query({
+        prompt: 'Count from 1 to 3',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      let assistantMessage: SDKAssistantMessage | null = null;
+
+      try {
+        for await (const message of q) {
+          if (isSDKAssistantMessage(message)) {
+            assistantMessage = message;
+          }
+        }
+
+        expect(assistantMessage).not.toBeNull();
+        expect(assistantMessage!.message.content).toBeDefined();
+
+        // Validate content contains expected numbers
+        const text = extractText(assistantMessage!.message.content);
+        expect(text.length).toBeGreaterThan(0);
+        expect(text).toMatch(/1/);
+        expect(text).toMatch(/2/);
+        expect(text).toMatch(/3/);
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should throw if CLI not found', async () => {
+      try {
+        const q = query({
+          prompt: 'Hello',
+          options: {
+            pathToQwenExecutable: '/nonexistent/path/to/cli',
+            debug: false,
+          },
+        });
+
+        for await (const _message of q) {
+          // Should not reach here
+        }
+
+        expect(false).toBe(true); // Should have thrown
+      } catch (error) {
+        expect(error).toBeDefined();
+        expect(error instanceof Error).toBe(true);
+        expect((error as Error).message).toContain(
+          'Invalid pathToQwenExecutable',
+        );
+      }
+    });
+  });
+
+  describe('Resource Management', () => {
+    it('should cleanup subprocess on close()', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      // Start and immediately close
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+
+      // Should close without error
+      await q.close();
+      expect(true).toBe(true); // Cleanup completed
+    });
+
+    it('should handle close() called multiple times', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          debug: false,
+        },
+      });
+
+      // Start the query
+      const iterator = q[Symbol.asyncIterator]();
+      await iterator.next();
+
+      // Close multiple times
+      await q.close();
+      await q.close();
+      await q.close();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+  });
+});

integration-tests/sdk-typescript/subagents.test.ts

@@ -0,0 +1,614 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for subagent configuration and execution
+ * Tests subagent delegation and task completion
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  type SDKMessage,
+  type SubagentConfig,
+  type ContentBlock,
+  type ToolUseBlock,
+} from '@qwen-code/sdk-typescript';
+import {
+  SDKTestHelper,
+  extractText,
+  createSharedTestOptions,
+  findToolUseBlocks,
+  assertSuccessfulCompletion,
+  findSystemMessage,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+describe('Subagents (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testWorkDir: string;
+
+  beforeEach(async () => {
+    // Create isolated test environment using SDKTestHelper
+    helper = new SDKTestHelper();
+    testWorkDir = await helper.setup('subagent-tests');
+
+    // Create a simple test file for subagent to work with
+    await helper.createFile('test.txt', 'Hello from test file\n');
+  });
+
+  afterEach(async () => {
+    // Cleanup test directory
+    await helper.cleanup();
+  });
+
+  describe('Subagent Configuration', () => {
+    it('should accept session-level subagent configuration', async () => {
+      const simpleSubagent: SubagentConfig = {
+        name: 'simple-greeter',
+        description: 'A simple subagent that responds to greetings',
+        systemPrompt:
+          'You are a friendly greeter. When given a task, respond with a cheerful greeting.',
+        level: 'session',
+      };
+
+      const q = query({
+        prompt: 'Hello, let simple-greeter to say hi back to me.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [simpleSubagent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate system message includes the subagent
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('simple-greeter');
+
+        // Validate successful completion
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should accept multiple subagent configurations', async () => {
+      const greeterAgent: SubagentConfig = {
+        name: 'greeter',
+        description: 'Responds to greetings',
+        systemPrompt: 'You are a friendly greeter.',
+        level: 'session',
+      };
+
+      const mathAgent: SubagentConfig = {
+        name: 'math-helper',
+        description: 'Helps with math problems',
+        systemPrompt: 'You are a math expert. Solve math problems clearly.',
+        level: 'session',
+      };
+
+      const q = query({
+        prompt: 'What is 5 + 5?',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [greeterAgent, mathAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate both subagents are registered
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('greeter');
+        expect(systemMessage!.agents).toContain('math-helper');
+        expect(systemMessage!.agents!.length).toBeGreaterThanOrEqual(2);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle subagent with custom model config', async () => {
+      const customModelAgent: SubagentConfig = {
+        name: 'custom-model-agent',
+        description: 'Agent with custom model configuration',
+        systemPrompt: 'You are a helpful assistant.',
+        level: 'session',
+        modelConfig: {
+          temp: 0.7,
+          top_p: 0.9,
+        },
+      };
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [customModelAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate subagent is registered
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('custom-model-agent');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle subagent with run config', async () => {
+      const limitedAgent: SubagentConfig = {
+        name: 'limited-agent',
+        description: 'Agent with execution limits',
+        systemPrompt: 'You are a helpful assistant.',
+        level: 'session',
+        runConfig: {
+          max_turns: 5,
+          max_time_minutes: 1,
+        },
+      };
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [limitedAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate subagent is registered
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('limited-agent');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle subagent with specific tools', async () => {
+      const toolRestrictedAgent: SubagentConfig = {
+        name: 'read-only-agent',
+        description: 'Agent that can only read files',
+        systemPrompt:
+          'You are a file reading assistant. Read files when asked.',
+        level: 'session',
+        tools: ['read_file', 'list_directory'],
+      };
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [toolRestrictedAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate subagent is registered
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('read-only-agent');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Subagent Execution', () => {
+    it('should delegate task to subagent when appropriate', async () => {
+      const fileReaderAgent: SubagentConfig = {
+        name: 'file-reader',
+        description: 'Reads and reports file contents',
+        systemPrompt: `You are a file reading assistant. When given a task to read a file, use the read_file tool to read it and report its contents back. Be concise in your response.`,
+        level: 'session',
+        tools: ['read_file', 'list_directory'],
+      };
+
+      const testFile = helper.getPath('test.txt');
+      const q = query({
+        prompt: `Use the file-reader subagent to read the file at ${testFile} and tell me what it contains.`,
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [fileReaderAgent],
+          debug: false,
+          permissionMode: 'yolo',
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let foundTaskTool = false;
+      let taskToolUseId: string | null = null;
+      let foundSubagentToolCall = false;
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            // Check for task tool use in content blocks (main agent calling subagent)
+            const taskToolBlocks = findToolUseBlocks(message, 'task');
+            if (taskToolBlocks.length > 0) {
+              foundTaskTool = true;
+              taskToolUseId = taskToolBlocks[0].id;
+            }
+
+            // Check if this message is from a subagent (has parent_tool_use_id)
+            if (message.parent_tool_use_id !== null) {
+              // This is a subagent message
+              const subagentToolBlocks = findToolUseBlocks(message);
+              if (subagentToolBlocks.length > 0) {
+                foundSubagentToolCall = true;
+                // Verify parent_tool_use_id matches the task tool use id
+                expect(message.parent_tool_use_id).toBe(taskToolUseId);
+              }
+            }
+
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate task tool was used (subagent delegation)
+        expect(foundTaskTool).toBe(true);
+        expect(taskToolUseId).not.toBeNull();
+
+        // Validate subagent actually made tool calls with proper parent_tool_use_id
+        expect(foundSubagentToolCall).toBe(true);
+
+        // Validate we got a response
+        expect(assistantText.length).toBeGreaterThan(0);
+
+        // Validate successful completion
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    }, 60000); // Increase timeout for subagent execution
+
+    it('should complete simple task with subagent', async () => {
+      const simpleTaskAgent: SubagentConfig = {
+        name: 'simple-calculator',
+        description: 'Performs simple arithmetic calculations',
+        systemPrompt:
+          'You are a calculator. When given a math problem, solve it and provide just the answer.',
+        level: 'session',
+      };
+
+      const q = query({
+        prompt: 'Use the simple-calculator subagent to calculate 15 + 27.',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [simpleTaskAgent],
+          debug: false,
+          permissionMode: 'yolo',
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let foundTaskTool = false;
+      let assistantText = '';
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            // Check for task tool use (main agent delegating to subagent)
+            const toolUseBlock = message.message.content.find(
+              (block: ContentBlock): block is ToolUseBlock =>
+                block.type === 'tool_use' && block.name === 'task',
+            );
+            if (toolUseBlock) {
+              foundTaskTool = true;
+            }
+
+            assistantText += extractText(message.message.content);
+          }
+        }
+
+        // Validate task tool was used (subagent was called)
+        expect(foundTaskTool).toBe(true);
+
+        // Validate we got a response
+        expect(assistantText.length).toBeGreaterThan(0);
+
+        // Validate successful completion
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    }, 60000);
+
+    it('should verify subagent execution with comprehensive parent_tool_use_id checks', async () => {
+      const comprehensiveAgent: SubagentConfig = {
+        name: 'comprehensive-agent',
+        description: 'Agent for comprehensive testing',
+        systemPrompt:
+          'You are a helpful assistant. When asked to list files, use the list_directory tool.',
+        level: 'session',
+        tools: ['list_directory', 'read_file'],
+      };
+
+      const q = query({
+        prompt: `Use the comprehensive-agent subagent to list the files in ${testWorkDir}.`,
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [comprehensiveAgent],
+          debug: false,
+          permissionMode: 'yolo',
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+      let taskToolUseId: string | null = null;
+      const subagentToolCalls: ToolUseBlock[] = [];
+      const mainAgentToolCalls: ToolUseBlock[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+
+          if (isSDKAssistantMessage(message)) {
+            // Collect all tool use blocks
+            const toolUseBlocks = message.message.content.filter(
+              (block: ContentBlock): block is ToolUseBlock =>
+                block.type === 'tool_use',
+            );
+
+            for (const toolUse of toolUseBlocks) {
+              if (toolUse.name === 'task') {
+                // This is the main agent calling the subagent
+                taskToolUseId = toolUse.id;
+                mainAgentToolCalls.push(toolUse);
+              }
+
+              // If this message has parent_tool_use_id, it's from a subagent
+              if (message.parent_tool_use_id !== null) {
+                subagentToolCalls.push(toolUse);
+              }
+            }
+          }
+        }
+
+        // Criterion 1: When a subagent is called, there must be a 'task' tool being called
+        expect(taskToolUseId).not.toBeNull();
+        expect(mainAgentToolCalls.length).toBeGreaterThan(0);
+        expect(mainAgentToolCalls.some((tc) => tc.name === 'task')).toBe(true);
+
+        // Criterion 2: A tool call from a subagent is identified by a non-null parent_tool_use_id
+        // All subagent tool calls should have parent_tool_use_id set to the task tool's id
+        expect(subagentToolCalls.length).toBeGreaterThan(0);
+
+        // Verify all subagent messages have the correct parent_tool_use_id
+        const subagentMessages = messages.filter(
+          (msg): msg is SDKMessage & { parent_tool_use_id: string } =>
+            isSDKAssistantMessage(msg) && msg.parent_tool_use_id !== null,
+        );
+
+        expect(subagentMessages.length).toBeGreaterThan(0);
+        for (const subagentMsg of subagentMessages) {
+          expect(subagentMsg.parent_tool_use_id).toBe(taskToolUseId);
+        }
+
+        // Verify no main agent tool calls (except task) have parent_tool_use_id
+        const mainAgentMessages = messages.filter(
+          (msg): msg is SDKMessage =>
+            isSDKAssistantMessage(msg) && msg.parent_tool_use_id === null,
+        );
+
+        for (const mainMsg of mainAgentMessages) {
+          if (isSDKAssistantMessage(mainMsg)) {
+            // Main agent messages should not have parent_tool_use_id
+            expect(mainMsg.parent_tool_use_id).toBeNull();
+          }
+        }
+
+        // Validate successful completion
+        assertSuccessfulCompletion(messages);
+      } finally {
+        await q.close();
+      }
+    }, 60000);
+  });
+
+  describe('Subagent Error Handling', () => {
+    it('should handle empty subagent array', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Should still work with empty agents array
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle subagent with minimal configuration', async () => {
+      const minimalAgent: SubagentConfig = {
+        name: 'minimal-agent',
+        description: 'Minimal configuration agent',
+        systemPrompt: 'You are a helpful assistant.',
+        level: 'session',
+      };
+
+      const q = query({
+        prompt: 'Say hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [minimalAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate minimal agent is registered
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('minimal-agent');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+
+  describe('Subagent Integration', () => {
+    it('should work with other SDK options', async () => {
+      const testAgent: SubagentConfig = {
+        name: 'test-agent',
+        description: 'Test agent for integration',
+        systemPrompt: 'You are a test assistant.',
+        level: 'session',
+      };
+
+      const stderrMessages: string[] = [];
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [testAgent],
+          debug: true,
+          stderr: (msg: string) => {
+            stderrMessages.push(msg);
+          },
+          permissionMode: 'default',
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate subagent works with debug mode
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.agents).toBeDefined();
+        expect(systemMessage!.agents).toContain('test-agent');
+        expect(stderrMessages.length).toBeGreaterThan(0);
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should maintain session consistency with subagents', async () => {
+      const sessionAgent: SubagentConfig = {
+        name: 'session-agent',
+        description: 'Agent for session testing',
+        systemPrompt: 'You are a session test assistant.',
+        level: 'session',
+      };
+
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testWorkDir,
+          agents: [sessionAgent],
+          debug: false,
+        },
+      });
+
+      const messages: SDKMessage[] = [];
+
+      try {
+        for await (const message of q) {
+          messages.push(message);
+        }
+
+        // Validate session consistency
+        const systemMessage = findSystemMessage(messages, 'init');
+        expect(systemMessage).not.toBeNull();
+        expect(systemMessage!.session_id).toBeDefined();
+        expect(systemMessage!.uuid).toBeDefined();
+        expect(systemMessage!.session_id).toBe(systemMessage!.uuid);
+        expect(systemMessage!.agents).toContain('session-agent');
+      } finally {
+        await q.close();
+      }
+    });
+  });
+});

integration-tests/sdk-typescript/system-control.test.ts

@@ -0,0 +1,317 @@
+/**
+ * E2E tests for system controller features:
+ * - setModel API for dynamic model switching
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  type SDKUserMessage,
+} from '@qwen-code/sdk-typescript';
+import { SDKTestHelper, createSharedTestOptions } from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+
+/**
+ * Factory function that creates a streaming input with a control point.
+ * After the first message is yielded, the generator waits for a resume signal,
+ * allowing the test code to call query instance methods like setModel.
+ *
+ * @param firstMessage - The first user message to send
+ * @param secondMessage - The second user message to send after control operations
+ * @returns Object containing the async generator and a resume function
+ */
+function createStreamingInputWithControlPoint(
+  firstMessage: string,
+  secondMessage: string,
+): {
+  generator: AsyncIterable<SDKUserMessage>;
+  resume: () => void;
+} {
+  let resumeResolve: (() => void) | null = null;
+  const resumePromise = new Promise<void>((resolve) => {
+    resumeResolve = resolve;
+  });
+
+  const generator = (async function* () {
+    const sessionId = crypto.randomUUID();
+
+    yield {
+      type: 'user',
+      session_id: sessionId,
+      message: {
+        role: 'user',
+        content: firstMessage,
+      },
+      parent_tool_use_id: null,
+    } as SDKUserMessage;
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    await resumePromise;
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    yield {
+      type: 'user',
+      session_id: sessionId,
+      message: {
+        role: 'user',
+        content: secondMessage,
+      },
+      parent_tool_use_id: null,
+    } as SDKUserMessage;
+  })();
+
+  const resume = () => {
+    if (resumeResolve) {
+      resumeResolve();
+    }
+  };
+
+  return { generator, resume };
+}
+
+describe('System Control (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('system-control');
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('setModel API', () => {
+    it('should change model dynamically during streaming input', async () => {
+      const { generator, resume } = createStreamingInputWithControlPoint(
+        'Tell me the model name.',
+        'Tell me the model name now again.',
+      );
+
+      const q = query({
+        prompt: generator,
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          model: 'qwen3-max',
+          debug: false,
+        },
+      });
+
+      try {
+        const resolvers: {
+          first?: () => void;
+          second?: () => void;
+        } = {};
+        const firstResponsePromise = new Promise<void>((resolve) => {
+          resolvers.first = resolve;
+        });
+        const secondResponsePromise = new Promise<void>((resolve) => {
+          resolvers.second = resolve;
+        });
+
+        let firstResponseReceived = false;
+        let secondResponseReceived = false;
+        const systemMessages: Array<{ model?: string }> = [];
+
+        // Consume messages in a single loop
+        (async () => {
+          for await (const message of q) {
+            if (isSDKSystemMessage(message)) {
+              systemMessages.push({ model: message.model });
+            }
+            if (isSDKAssistantMessage(message)) {
+              if (!firstResponseReceived) {
+                firstResponseReceived = true;
+                resolvers.first?.();
+              } else if (!secondResponseReceived) {
+                secondResponseReceived = true;
+                resolvers.second?.();
+              }
+            }
+          }
+        })();
+
+        // Wait for first response
+        await Promise.race([
+          firstResponsePromise,
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error('Timeout waiting for first response')),
+              15000,
+            ),
+          ),
+        ]);
+
+        expect(firstResponseReceived).toBe(true);
+
+        // Perform control operation: set model
+        await q.setModel('qwen3-vl-plus');
+
+        // Resume the input stream
+        resume();
+
+        // Wait for second response
+        await Promise.race([
+          secondResponsePromise,
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error('Timeout waiting for second response')),
+              10000,
+            ),
+          ),
+        ]);
+
+        expect(secondResponseReceived).toBe(true);
+
+        // Verify system messages - model should change from qwen3-max to qwen3-vl-plus
+        expect(systemMessages.length).toBeGreaterThanOrEqual(2);
+        expect(systemMessages[0].model).toBeOneOf(['qwen3-max', 'coder-model']);
+        expect(systemMessages[1].model).toBe('qwen3-vl-plus');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should handle multiple model changes in sequence', async () => {
+      const sessionId = crypto.randomUUID();
+      let resumeResolve1: (() => void) | null = null;
+      let resumeResolve2: (() => void) | null = null;
+      const resumePromise1 = new Promise<void>((resolve) => {
+        resumeResolve1 = resolve;
+      });
+      const resumePromise2 = new Promise<void>((resolve) => {
+        resumeResolve2 = resolve;
+      });
+
+      const generator = (async function* () {
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: { role: 'user', content: 'First message' },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        await resumePromise1;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: { role: 'user', content: 'Second message' },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        await resumePromise2;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+
+        yield {
+          type: 'user',
+          session_id: sessionId,
+          message: { role: 'user', content: 'Third message' },
+          parent_tool_use_id: null,
+        } as SDKUserMessage;
+      })();
+
+      const q = query({
+        prompt: generator,
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          model: 'qwen3-max',
+          debug: false,
+        },
+      });
+
+      try {
+        const systemMessages: Array<{ model?: string }> = [];
+        let responseCount = 0;
+        const resolvers: Array<() => void> = [];
+        const responsePromises = [
+          new Promise<void>((resolve) => resolvers.push(resolve)),
+          new Promise<void>((resolve) => resolvers.push(resolve)),
+          new Promise<void>((resolve) => resolvers.push(resolve)),
+        ];
+
+        (async () => {
+          for await (const message of q) {
+            if (isSDKSystemMessage(message)) {
+              systemMessages.push({ model: message.model });
+            }
+            if (isSDKAssistantMessage(message)) {
+              if (responseCount < resolvers.length) {
+                resolvers[responseCount]?.();
+                responseCount++;
+              }
+            }
+          }
+        })();
+
+        // Wait for first response
+        await Promise.race([
+          responsePromises[0],
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Timeout 1')), 10000),
+          ),
+        ]);
+
+        // First model change
+        await q.setModel('qwen3-turbo');
+        resumeResolve1!();
+
+        // Wait for second response
+        await Promise.race([
+          responsePromises[1],
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Timeout 2')), 10000),
+          ),
+        ]);
+
+        // Second model change
+        await q.setModel('qwen3-vl-plus');
+        resumeResolve2!();
+
+        // Wait for third response
+        await Promise.race([
+          responsePromises[2],
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Timeout 3')), 10000),
+          ),
+        ]);
+
+        // Verify we received system messages for each model
+        expect(systemMessages.length).toBeGreaterThanOrEqual(3);
+        expect(systemMessages[0].model).toBeOneOf(['qwen3-max', 'coder-model']);
+        expect(systemMessages[1].model).toBe('qwen3-turbo');
+        expect(systemMessages[2].model).toBe('qwen3-vl-plus');
+      } finally {
+        await q.close();
+      }
+    });
+
+    it('should throw error when setModel is called on closed query', async () => {
+      const q = query({
+        prompt: 'Hello',
+        options: {
+          ...SHARED_TEST_OPTIONS,
+          cwd: testDir,
+          model: 'qwen3-max',
+        },
+      });
+
+      await q.close();
+
+      await expect(q.setModel('qwen3-turbo')).rejects.toThrow(
+        'Query is closed',
+      );
+    });
+  });
+});

integration-tests/sdk-typescript/test-helper.ts

@@ -0,0 +1,970 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * SDK E2E Test Helper
+ * Provides utilities for SDK e2e tests including test isolation,
+ * file management, MCP server setup, and common test utilities.
+ */
+
+import { mkdir, writeFile, readFile, rm, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import type {
+  SDKMessage,
+  SDKAssistantMessage,
+  SDKSystemMessage,
+  SDKUserMessage,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+} from '@qwen-code/sdk-typescript';
+import {
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+} from '@qwen-code/sdk-typescript';
+
+// ============================================================================
+// Core Test Helper Class
+// ============================================================================
+
+export interface SDKTestHelperOptions {
+  /**
+   * Optional settings for .qwen/settings.json
+   */
+  settings?: Record<string, unknown>;
+  /**
+   * Whether to create .qwen/settings.json
+   */
+  createQwenConfig?: boolean;
+}
+
+/**
+ * Helper class for SDK E2E tests
+ * Provides isolated test environments for each test case
+ */
+export class SDKTestHelper {
+  testDir: string | null = null;
+  testName?: string;
+  private baseDir: string;
+
+  constructor() {
+    this.baseDir = process.env['E2E_TEST_FILE_DIR']!;
+    if (!this.baseDir) {
+      throw new Error('E2E_TEST_FILE_DIR environment variable not set');
+    }
+  }
+
+  /**
+   * Setup an isolated test directory for a specific test
+   */
+  async setup(
+    testName: string,
+    options: SDKTestHelperOptions = {},
+  ): Promise<string> {
+    this.testName = testName;
+    const sanitizedName = this.sanitizeTestName(testName);
+    this.testDir = join(this.baseDir, sanitizedName);
+
+    await mkdir(this.testDir, { recursive: true });
+
+    // Optionally create .qwen/settings.json for CLI configuration
+    if (options.createQwenConfig) {
+      const qwenDir = join(this.testDir, '.qwen');
+      await mkdir(qwenDir, { recursive: true });
+
+      const settings = {
+        telemetry: {
+          enabled: false, // SDK tests don't need telemetry
+        },
+        ...options.settings,
+      };
+
+      await writeFile(
+        join(qwenDir, 'settings.json'),
+        JSON.stringify(settings, null, 2),
+        'utf-8',
+      );
+    }
+
+    return this.testDir;
+  }
+
+  /**
+   * Create a file in the test directory
+   */
+  async createFile(fileName: string, content: string): Promise<string> {
+    if (!this.testDir) {
+      throw new Error('Test directory not initialized. Call setup() first.');
+    }
+    const filePath = join(this.testDir, fileName);
+    await writeFile(filePath, content, 'utf-8');
+    return filePath;
+  }
+
+  /**
+   * Read a file from the test directory
+   */
+  async readFile(fileName: string): Promise<string> {
+    if (!this.testDir) {
+      throw new Error('Test directory not initialized. Call setup() first.');
+    }
+    const filePath = join(this.testDir, fileName);
+    return await readFile(filePath, 'utf-8');
+  }
+
+  /**
+   * Create a subdirectory in the test directory
+   */
+  async mkdir(dirName: string): Promise<string> {
+    if (!this.testDir) {
+      throw new Error('Test directory not initialized. Call setup() first.');
+    }
+    const dirPath = join(this.testDir, dirName);
+    await mkdir(dirPath, { recursive: true });
+    return dirPath;
+  }
+
+  /**
+   * Check if a file exists in the test directory
+   */
+  fileExists(fileName: string): boolean {
+    if (!this.testDir) {
+      throw new Error('Test directory not initialized. Call setup() first.');
+    }
+    const filePath = join(this.testDir, fileName);
+    return existsSync(filePath);
+  }
+
+  /**
+   * Get the full path to a file in the test directory
+   */
+  getPath(fileName: string): string {
+    if (!this.testDir) {
+      throw new Error('Test directory not initialized. Call setup() first.');
+    }
+    return join(this.testDir, fileName);
+  }
+
+  /**
+   * Cleanup test directory
+   */
+  async cleanup(): Promise<void> {
+    if (this.testDir && process.env['KEEP_OUTPUT'] !== 'true') {
+      try {
+        await rm(this.testDir, { recursive: true, force: true });
+      } catch (error) {
+        if (process.env['VERBOSE'] === 'true') {
+          console.warn('Cleanup warning:', (error as Error).message);
+        }
+      }
+    }
+  }
+
+  /**
+   * Sanitize test name to create valid directory name
+   */
+  private sanitizeTestName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, '-')
+      .replace(/-+/g, '-')
+      .substring(0, 100); // Limit length
+  }
+}
+
+// ============================================================================
+// MCP Server Utilities
+// ============================================================================
+
+export interface MCPServerConfig {
+  command: string;
+  args: string[];
+}
+
+export interface MCPServerResult {
+  scriptPath: string;
+  config: MCPServerConfig;
+}
+
+/**
+ * Built-in MCP server template: Math server with add and multiply tools
+ */
+const MCP_MATH_SERVER_SCRIPT = `#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const readline = require('readline');
+const fs = require('fs');
+
+// Debug logging to stderr (only when MCP_DEBUG or VERBOSE is set)
+const debugEnabled = process.env['MCP_DEBUG'] === 'true' || process.env['VERBOSE'] === 'true';
+function debug(msg) {
+  if (debugEnabled) {
+    fs.writeSync(2, \`[MCP-DEBUG] \${msg}\\n\`);
+  }
+}
+
+debug('MCP server starting...');
+
+// Simple JSON-RPC implementation for MCP
+class SimpleJSONRPC {
+  constructor() {
+    this.handlers = new Map();
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false
+    });
+    
+    this.rl.on('line', (line) => {
+      debug(\`Received line: \${line}\`);
+      try {
+        const message = JSON.parse(line);
+        debug(\`Parsed message: \${JSON.stringify(message)}\`);
+        this.handleMessage(message);
+      } catch (e) {
+        debug(\`Parse error: \${e.message}\`);
+      }
+    });
+  }
+  
+  send(message) {
+    const msgStr = JSON.stringify(message);
+    debug(\`Sending message: \${msgStr}\`);
+    process.stdout.write(msgStr + '\\n');
+  }
+  
+  async handleMessage(message) {
+    if (message.method && this.handlers.has(message.method)) {
+      try {
+        const result = await this.handlers.get(message.method)(message.params || {});
+        if (message.id !== undefined) {
+          this.send({
+            jsonrpc: '2.0',
+            id: message.id,
+            result
+          });
+        }
+      } catch (error) {
+        if (message.id !== undefined) {
+          this.send({
+            jsonrpc: '2.0',
+            id: message.id,
+            error: {
+              code: -32603,
+              message: error.message
+            }
+          });
+        }
+      }
+    } else if (message.id !== undefined) {
+      this.send({
+        jsonrpc: '2.0',
+        id: message.id,
+        error: {
+          code: -32601,
+          message: 'Method not found'
+        }
+      });
+    }
+  }
+  
+  on(method, handler) {
+    this.handlers.set(method, handler);
+  }
+}
+
+// Create MCP server
+const rpc = new SimpleJSONRPC();
+
+// Handle initialize
+rpc.on('initialize', async (params) => {
+  debug('Handling initialize request');
+  return {
+    protocolVersion: '2024-11-05',
+    capabilities: {
+      tools: {}
+    },
+    serverInfo: {
+      name: 'test-math-server',
+      version: '1.0.0'
+    }
+  };
+});
+
+// Handle tools/list
+rpc.on('tools/list', async () => {
+  debug('Handling tools/list request');
+  return {
+    tools: [
+      {
+        name: 'add',
+        description: 'Add two numbers together',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            a: { type: 'number', description: 'First number' },
+            b: { type: 'number', description: 'Second number' }
+          },
+          required: ['a', 'b']
+        }
+      },
+      {
+        name: 'multiply',
+        description: 'Multiply two numbers together',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            a: { type: 'number', description: 'First number' },
+            b: { type: 'number', description: 'Second number' }
+          },
+          required: ['a', 'b']
+        }
+      }
+    ]
+  };
+});
+
+// Handle tools/call
+rpc.on('tools/call', async (params) => {
+  debug(\`Handling tools/call request for tool: \${params.name}\`);
+  
+  if (params.name === 'add') {
+    const { a, b } = params.arguments;
+    return {
+      content: [{
+        type: 'text',
+        text: String(a + b)
+      }]
+    };
+  }
+  
+  if (params.name === 'multiply') {
+    const { a, b } = params.arguments;
+    return {
+      content: [{
+        type: 'text',
+        text: String(a * b)
+      }]
+    };
+  }
+  
+  throw new Error('Unknown tool: ' + params.name);
+});
+
+// Send initialization notification
+rpc.send({
+  jsonrpc: '2.0',
+  method: 'initialized'
+});
+`;
+
+/**
+ * Create an MCP server script in the test directory
+ * @param helper - SDKTestHelper instance
+ * @param type - Type of MCP server ('math' or provide custom script)
+ * @param serverName - Name of the MCP server (default: 'test-math-server')
+ * @param customScript - Custom MCP server script (if type is not 'math')
+ * @returns Object with scriptPath and config
+ */
+export async function createMCPServer(
+  helper: SDKTestHelper,
+  type: 'math' | 'custom' = 'math',
+  serverName: string = 'test-math-server',
+  customScript?: string,
+): Promise<MCPServerResult> {
+  if (!helper.testDir) {
+    throw new Error('Test directory not initialized. Call setup() first.');
+  }
+
+  const script = type === 'math' ? MCP_MATH_SERVER_SCRIPT : customScript;
+  if (!script) {
+    throw new Error('Custom script required when type is "custom"');
+  }
+
+  const scriptPath = join(helper.testDir, `${serverName}.cjs`);
+  await writeFile(scriptPath, script, 'utf-8');
+
+  // Make script executable on Unix-like systems
+  if (process.platform !== 'win32') {
+    await chmod(scriptPath, 0o755);
+  }
+
+  return {
+    scriptPath,
+    config: {
+      command: 'node',
+      args: [scriptPath],
+    },
+  };
+}
+
+// ============================================================================
+// Message & Content Utilities
+// ============================================================================
+
+/**
+ * Extract text from ContentBlock array
+ */
+export function extractText(content: ContentBlock[]): string {
+  return content
+    .filter((block): block is TextBlock => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+}
+
+/**
+ * Collect messages by type
+ */
+export function collectMessagesByType<T extends SDKMessage>(
+  messages: SDKMessage[],
+  predicate: (msg: SDKMessage) => msg is T,
+): T[] {
+  return messages.filter(predicate);
+}
+
+/**
+ * Find tool use blocks in a message
+ */
+export function findToolUseBlocks(
+  message: SDKAssistantMessage,
+  toolName?: string,
+): ToolUseBlock[] {
+  const toolUseBlocks = message.message.content.filter(
+    (block): block is ToolUseBlock => block.type === 'tool_use',
+  );
+
+  if (toolName) {
+    return toolUseBlocks.filter((block) => block.name === toolName);
+  }
+
+  return toolUseBlocks;
+}
+
+/**
+ * Extract all assistant text from messages
+ */
+export function getAssistantText(messages: SDKMessage[]): string {
+  return messages
+    .filter(isSDKAssistantMessage)
+    .map((msg) => extractText(msg.message.content))
+    .join('');
+}
+
+/**
+ * Find system message with optional subtype filter
+ */
+export function findSystemMessage(
+  messages: SDKMessage[],
+  subtype?: string,
+): SDKSystemMessage | null {
+  const systemMessages = messages.filter(isSDKSystemMessage);
+
+  if (subtype) {
+    return systemMessages.find((msg) => msg.subtype === subtype) || null;
+  }
+
+  return systemMessages[0] || null;
+}
+
+/**
+ * Find all tool calls in messages
+ */
+export function findToolCalls(
+  messages: SDKMessage[],
+  toolName?: string,
+): Array<{ message: SDKAssistantMessage; toolUse: ToolUseBlock }> {
+  const results: Array<{
+    message: SDKAssistantMessage;
+    toolUse: ToolUseBlock;
+  }> = [];
+
+  for (const message of messages) {
+    if (isSDKAssistantMessage(message)) {
+      const toolUseBlocks = findToolUseBlocks(message, toolName);
+      for (const toolUse of toolUseBlocks) {
+        results.push({ message, toolUse });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find tool result for a specific tool use ID
+ */
+export function findToolResult(
+  messages: SDKMessage[],
+  toolUseId: string,
+): { content: string; isError: boolean } | null {
+  for (const message of messages) {
+    if (message.type === 'user' && 'message' in message) {
+      const userMsg = message as SDKUserMessage;
+      const content = userMsg.message.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (
+            block.type === 'tool_result' &&
+            (block as { tool_use_id?: string }).tool_use_id === toolUseId
+          ) {
+            const resultBlock = block as {
+              content?: string | ContentBlock[];
+              is_error?: boolean;
+            };
+            let resultContent = '';
+            if (typeof resultBlock.content === 'string') {
+              resultContent = resultBlock.content;
+            } else if (Array.isArray(resultBlock.content)) {
+              resultContent = resultBlock.content
+                .filter((b): b is TextBlock => b.type === 'text')
+                .map((b) => b.text)
+                .join('');
+            }
+            return {
+              content: resultContent,
+              isError: resultBlock.is_error ?? false,
+            };
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Find all tool results for a specific tool name
+ */
+export function findToolResults(
+  messages: SDKMessage[],
+  toolName: string,
+): Array<{ toolUseId: string; content: string; isError: boolean }> {
+  const results: Array<{
+    toolUseId: string;
+    content: string;
+    isError: boolean;
+  }> = [];
+
+  // First find all tool calls for this tool
+  const toolCalls = findToolCalls(messages, toolName);
+
+  // Then find the result for each tool call
+  for (const { toolUse } of toolCalls) {
+    const result = findToolResult(messages, toolUse.id);
+    if (result) {
+      results.push({
+        toolUseId: toolUse.id,
+        content: result.content,
+        isError: result.isError,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find all tool result blocks from messages (without requiring tool name)
+ */
+export function findAllToolResultBlocks(
+  messages: SDKMessage[],
+): Array<{ toolUseId: string; content: string; isError: boolean }> {
+  const results: Array<{
+    toolUseId: string;
+    content: string;
+    isError: boolean;
+  }> = [];
+
+  for (const message of messages) {
+    if (message.type === 'user' && 'message' in message) {
+      const userMsg = message as SDKUserMessage;
+      const content = userMsg.message.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'tool_result' && 'tool_use_id' in block) {
+            const resultBlock = block as {
+              tool_use_id: string;
+              content?: string | ContentBlock[];
+              is_error?: boolean;
+            };
+            let resultContent = '';
+            if (typeof resultBlock.content === 'string') {
+              resultContent = resultBlock.content;
+            } else if (Array.isArray(resultBlock.content)) {
+              resultContent = (resultBlock.content as ContentBlock[])
+                .filter((b): b is TextBlock => b.type === 'text')
+                .map((b) => b.text)
+                .join('');
+            }
+            results.push({
+              toolUseId: resultBlock.tool_use_id,
+              content: resultContent,
+              isError: resultBlock.is_error ?? false,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if any tool results exist in messages
+ */
+export function hasAnyToolResults(messages: SDKMessage[]): boolean {
+  return findAllToolResultBlocks(messages).length > 0;
+}
+
+/**
+ * Check if any successful (non-error) tool results exist
+ */
+export function hasSuccessfulToolResults(messages: SDKMessage[]): boolean {
+  return findAllToolResultBlocks(messages).some((r) => !r.isError);
+}
+
+/**
+ * Check if any error tool results exist
+ */
+export function hasErrorToolResults(messages: SDKMessage[]): boolean {
+  return findAllToolResultBlocks(messages).some((r) => r.isError);
+}
+
+// ============================================================================
+// Streaming Input Utilities
+// ============================================================================
+
+/**
+ * Create a simple streaming input from an array of message contents
+ */
+export async function* createStreamingInput(
+  messageContents: string[],
+  sessionId?: string,
+): AsyncIterable<SDKUserMessage> {
+  const sid = sessionId || crypto.randomUUID();
+
+  for (const content of messageContents) {
+    yield {
+      type: 'user',
+      session_id: sid,
+      message: {
+        role: 'user',
+        content: content,
+      },
+      parent_tool_use_id: null,
+    } as SDKUserMessage;
+
+    // Small delay between messages
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+/**
+ * Create a controlled streaming input with pause/resume capability
+ */
+export function createControlledStreamingInput(
+  messageContents: string[],
+  sessionId?: string,
+): {
+  generator: AsyncIterable<SDKUserMessage>;
+  resume: () => void;
+  resumeAll: () => void;
+} {
+  const sid = sessionId || crypto.randomUUID();
+  const resumeResolvers: Array<() => void> = [];
+  const resumePromises: Array<Promise<void>> = [];
+
+  // Create a resume promise for each message after the first
+  for (let i = 1; i < messageContents.length; i++) {
+    const promise = new Promise<void>((resolve) => {
+      resumeResolvers.push(resolve);
+    });
+    resumePromises.push(promise);
+  }
+
+  const generator = (async function* () {
+    // Yield first message immediately
+    yield {
+      type: 'user',
+      session_id: sid,
+      message: {
+        role: 'user',
+        content: messageContents[0],
+      },
+      parent_tool_use_id: null,
+    } as SDKUserMessage;
+
+    // For subsequent messages, wait for resume
+    for (let i = 1; i < messageContents.length; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      await resumePromises[i - 1];
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      yield {
+        type: 'user',
+        session_id: sid,
+        message: {
+          role: 'user',
+          content: messageContents[i],
+        },
+        parent_tool_use_id: null,
+      } as SDKUserMessage;
+    }
+  })();
+
+  let currentResumeIndex = 0;
+
+  return {
+    generator,
+    resume: () => {
+      if (currentResumeIndex < resumeResolvers.length) {
+        resumeResolvers[currentResumeIndex]();
+        currentResumeIndex++;
+      }
+    },
+    resumeAll: () => {
+      resumeResolvers.forEach((resolve) => resolve());
+      currentResumeIndex = resumeResolvers.length;
+    },
+  };
+}
+
+// ============================================================================
+// Assertion Utilities
+// ============================================================================
+
+/**
+ * Assert that messages follow expected type sequence
+ */
+export function assertMessageSequence(
+  messages: SDKMessage[],
+  expectedTypes: string[],
+): void {
+  const actualTypes = messages.map((msg) => msg.type);
+
+  if (actualTypes.length < expectedTypes.length) {
+    throw new Error(
+      `Expected at least ${expectedTypes.length} messages, got ${actualTypes.length}`,
+    );
+  }
+
+  for (let i = 0; i < expectedTypes.length; i++) {
+    if (actualTypes[i] !== expectedTypes[i]) {
+      throw new Error(
+        `Expected message ${i} to be type '${expectedTypes[i]}', got '${actualTypes[i]}'`,
+      );
+    }
+  }
+}
+
+/**
+ * Assert that a specific tool was called
+ */
+export function assertToolCalled(
+  messages: SDKMessage[],
+  toolName: string,
+): void {
+  const toolCalls = findToolCalls(messages, toolName);
+
+  if (toolCalls.length === 0) {
+    const allToolCalls = findToolCalls(messages);
+    const allToolNames = allToolCalls.map((tc) => tc.toolUse.name);
+    throw new Error(
+      `Expected tool '${toolName}' to be called. Found tools: ${allToolNames.length > 0 ? allToolNames.join(', ') : 'none'}`,
+    );
+  }
+}
+
+/**
+ * Assert that the conversation completed successfully
+ */
+export function assertSuccessfulCompletion(messages: SDKMessage[]): void {
+  const lastMessage = messages[messages.length - 1];
+
+  if (!isSDKResultMessage(lastMessage)) {
+    throw new Error(
+      `Expected last message to be a result message, got '${lastMessage.type}'`,
+    );
+  }
+
+  if (lastMessage.subtype !== 'success') {
+    throw new Error(
+      `Expected successful completion, got result subtype '${lastMessage.subtype}'`,
+    );
+  }
+}
+
+/**
+ * Wait for a condition to be true with timeout
+ */
+export async function waitFor(
+  predicate: () => boolean | Promise<boolean>,
+  options: {
+    timeout?: number;
+    interval?: number;
+    errorMessage?: string;
+  } = {},
+): Promise<void> {
+  const {
+    timeout = 5000,
+    interval = 100,
+    errorMessage = 'Condition not met within timeout',
+  } = options;
+
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    const result = await predicate();
+    if (result) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+
+  throw new Error(errorMessage);
+}
+
+// ============================================================================
+// Debug and Validation Utilities
+// ============================================================================
+
+/**
+ * Validate model output and warn about unexpected content
+ * Inspired by integration-tests test-helper
+ */
+export function validateModelOutput(
+  result: string,
+  expectedContent: string | (string | RegExp)[] | null = null,
+  testName = '',
+): boolean {
+  // First, check if there's any output at all
+  if (!result || result.trim().length === 0) {
+    throw new Error('Expected model to return some output');
+  }
+
+  // If expectedContent is provided, check for it and warn if missing
+  if (expectedContent) {
+    const contents = Array.isArray(expectedContent)
+      ? expectedContent
+      : [expectedContent];
+    const missingContent = contents.filter((content) => {
+      if (typeof content === 'string') {
+        return !result.toLowerCase().includes(content.toLowerCase());
+      } else if (content instanceof RegExp) {
+        return !content.test(result);
+      }
+      return false;
+    });
+
+    if (missingContent.length > 0) {
+      console.warn(
+        `Warning: Model did not include expected content in response: ${missingContent.join(', ')}.`,
+        'This is not ideal but not a test failure.',
+      );
+      console.warn(
+        'The tool was called successfully, which is the main requirement.',
+      );
+      return false;
+    } else if (process.env['VERBOSE'] === 'true') {
+      console.log(`${testName}: Model output validated successfully.`);
+    }
+    return true;
+  }
+
+  return true;
+}
+
+/**
+ * Print debug information when tests fail
+ */
+export function printDebugInfo(
+  messages: SDKMessage[],
+  context: Record<string, unknown> = {},
+): void {
+  console.error('Test failed - Debug info:');
+  console.error('Message count:', messages.length);
+
+  // Print message types
+  const messageTypes = messages.map((m) => m.type);
+  console.error('Message types:', messageTypes.join(', '));
+
+  // Print assistant text
+  const assistantText = getAssistantText(messages);
+  console.error(
+    'Assistant text (first 500 chars):',
+    assistantText.substring(0, 500),
+  );
+  if (assistantText.length > 500) {
+    console.error(
+      'Assistant text (last 500 chars):',
+      assistantText.substring(assistantText.length - 500),
+    );
+  }
+
+  // Print tool calls
+  const toolCalls = findToolCalls(messages);
+  console.error(
+    'Tool calls found:',
+    toolCalls.map((tc) => tc.toolUse.name),
+  );
+
+  // Print any additional context provided
+  Object.entries(context).forEach(([key, value]) => {
+    console.error(`${key}:`, value);
+  });
+}
+
+/**
+ * Create detailed error message for tool call expectations
+ */
+export function createToolCallErrorMessage(
+  expectedTools: string | string[],
+  foundTools: string[],
+  messages: SDKMessage[],
+): string {
+  const expectedStr = Array.isArray(expectedTools)
+    ? expectedTools.join(' or ')
+    : expectedTools;
+
+  const assistantText = getAssistantText(messages);
+  const preview = assistantText
+    ? assistantText.substring(0, 200) + '...'
+    : 'no output';
+
+  return (
+    `Expected to find ${expectedStr} tool call(s). ` +
+    `Found: ${foundTools.length > 0 ? foundTools.join(', ') : 'none'}. ` +
+    `Output preview: ${preview}`
+  );
+}
+
+// ============================================================================
+// Shared Test Options Helper
+// ============================================================================
+
+/**
+ * Create shared test options with CLI path
+ */
+export function createSharedTestOptions(
+  overrides: Record<string, unknown> = {},
+) {
+  const TEST_CLI_PATH = process.env['TEST_CLI_PATH'];
+  if (!TEST_CLI_PATH) {
+    throw new Error('TEST_CLI_PATH environment variable not set');
+  }
+
+  return {
+    pathToQwenExecutable: TEST_CLI_PATH,
+    ...overrides,
+  };
+}

integration-tests/sdk-typescript/tool-control.test.ts

@@ -0,0 +1,748 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * E2E tests for tool control parameters:
+ * - coreTools: Limit available tools to a specific set
+ * - excludeTools: Block specific tools from execution
+ * - allowedTools: Auto-approve specific tools without confirmation
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  query,
+  isSDKAssistantMessage,
+  type SDKMessage,
+} from '@qwen-code/sdk-typescript';
+import {
+  SDKTestHelper,
+  extractText,
+  findToolCalls,
+  findToolResults,
+  assertSuccessfulCompletion,
+  createSharedTestOptions,
+} from './test-helper.js';
+
+const SHARED_TEST_OPTIONS = createSharedTestOptions();
+const TEST_TIMEOUT = 60000;
+
+describe('Tool Control Parameters (E2E)', () => {
+  let helper: SDKTestHelper;
+  let testDir: string;
+
+  beforeEach(async () => {
+    helper = new SDKTestHelper();
+    testDir = await helper.setup('tool-control', {
+      createQwenConfig: false,
+    });
+  });
+
+  afterEach(async () => {
+    await helper.cleanup();
+  });
+
+  describe('coreTools parameter', () => {
+    it(
+      'should only allow specified tools when coreTools is set',
+      async () => {
+        // Create a test file
+        await helper.createFile('test.txt', 'original content');
+
+        const q = query({
+          prompt:
+            'Read the file test.txt and then write "modified" to test.txt. Finally, list the directory.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Only allow read_file and write_file, exclude list_directory
+            coreTools: ['read_file', 'write_file'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          // Should have read_file and write_file calls
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+
+          // Should NOT have list_directory since it's not in coreTools
+          expect(toolNames).not.toContain('list_directory');
+
+          // Verify file was modified
+          const content = await helper.readFile('test.txt');
+          expect(content).toContain('modified');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should work with minimal tool set',
+      async () => {
+        const q = query({
+          prompt: 'What is 2 + 2? Just answer with the number.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            // Only allow thinking, no file operations
+            coreTools: [],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+        let assistantText = '';
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+
+            if (isSDKAssistantMessage(message)) {
+              assistantText += extractText(message.message.content);
+            }
+          }
+
+          // Should answer without any tool calls
+          expect(assistantText).toMatch(/4/);
+
+          // Should have no tool calls
+          const toolCalls = findToolCalls(messages);
+          expect(toolCalls.length).toBe(0);
+
+          assertSuccessfulCompletion(messages);
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+  });
+
+  describe('excludeTools parameter', () => {
+    it(
+      'should block excluded tools from execution',
+      async () => {
+        await helper.createFile('test.txt', 'test content');
+
+        const q = query({
+          prompt:
+            'Read test.txt and then write empty content to it to clear it.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            coreTools: ['read_file', 'write_file'],
+            // Block all write_file tool
+            excludeTools: ['write_file'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should be able to read the file
+          expect(toolNames).toContain('read_file');
+
+          // The excluded tools should have been called but returned permission declined
+          // Check if write_file was attempted and got permission denied
+          const writeFileResults = findToolResults(messages, 'write_file');
+          if (writeFileResults.length > 0) {
+            // Tool was called but should have permission declined message
+            for (const result of writeFileResults) {
+              expect(result.content).toMatch(/permission.*declined/i);
+            }
+          }
+
+          // File content should remain unchanged (because write was denied)
+          const content = await helper.readFile('test.txt');
+          expect(content).toBe('test content');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should block multiple excluded tools',
+      async () => {
+        await helper.createFile('test.txt', 'test content');
+
+        const q = query({
+          prompt: 'Read test.txt, list the directory, and run "echo hello".',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Block multiple tools
+            excludeTools: ['list_directory', 'run_shell_command'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should be able to read
+          expect(toolNames).toContain('read_file');
+
+          // Excluded tools should have been attempted but returned permission declined
+          const listDirResults = findToolResults(messages, 'list_directory');
+          if (listDirResults.length > 0) {
+            for (const result of listDirResults) {
+              expect(result.content).toMatch(/permission.*declined/i);
+            }
+          }
+
+          const shellResults = findToolResults(messages, 'run_shell_command');
+          if (shellResults.length > 0) {
+            for (const result of shellResults) {
+              expect(result.content).toMatch(/permission.*declined/i);
+            }
+          }
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should block all shell commands when run_shell_command is excluded',
+      async () => {
+        const q = query({
+          prompt: 'Run "echo hello" and "ls -la" commands.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Block all shell commands - excludeTools blocks entire tools
+            excludeTools: ['run_shell_command'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          // All shell commands should have permission declined
+          const shellResults = findToolResults(messages, 'run_shell_command');
+          for (const result of shellResults) {
+            expect(result.content).toMatch(/permission.*declined/i);
+          }
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'excludeTools should take priority over allowedTools',
+      async () => {
+        await helper.createFile('test.txt', 'test content');
+
+        const q = query({
+          prompt:
+            'Clear the content of test.txt by writing empty string to it.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            // Conflicting settings: exclude takes priority
+            excludeTools: ['write_file'],
+            allowedTools: ['write_file'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          // write_file should have been attempted but returned permission declined
+          const writeFileResults = findToolResults(messages, 'write_file');
+          if (writeFileResults.length > 0) {
+            // Tool was called but should have permission declined message (exclude takes priority)
+            for (const result of writeFileResults) {
+              expect(result.content).toMatch(/permission.*declined/i);
+            }
+          }
+
+          // File content should remain unchanged (because write was denied)
+          const content = await helper.readFile('test.txt');
+          expect(content).toBe('test content');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+  });
+
+  describe('allowedTools parameter', () => {
+    it(
+      'should auto-approve allowed tools without canUseTool callback',
+      async () => {
+        await helper.createFile('test.txt', 'original');
+
+        let canUseToolCalled = false;
+
+        const q = query({
+          prompt: 'Read test.txt and write "modified" to it.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            coreTools: ['read_file', 'write_file'],
+            // Allow write_file without confirmation
+            allowedTools: ['read_file', 'write_file'],
+            canUseTool: async (_toolName) => {
+              canUseToolCalled = true;
+              return { behavior: 'deny', message: 'Should not be called' };
+            },
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should have executed the tools
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+
+          // canUseTool should NOT have been called (tools are in allowedTools)
+          expect(canUseToolCalled).toBe(false);
+
+          // Verify file was modified
+          const content = await helper.readFile('test.txt');
+          expect(content).toContain('modified');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should allow specific shell commands with pattern matching',
+      async () => {
+        const q = query({
+          prompt: 'Run "echo hello" and "ls -la" commands.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            // Allow specific shell commands
+            allowedTools: ['ShellTool(echo )', 'ShellTool(ls )'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const shellCalls = toolCalls.filter(
+            (tc) => tc.toolUse.name === 'run_shell_command',
+          );
+
+          // Should have executed shell commands
+          expect(shellCalls.length).toBeGreaterThan(0);
+
+          // All shell commands should be echo or ls
+          for (const call of shellCalls) {
+            const input = call.toolUse.input as { command?: string };
+            if (input.command) {
+              expect(input.command).toMatch(/^(echo |ls )/);
+            }
+          }
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should fall back to canUseTool for non-allowed tools',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const canUseToolCalls: string[] = [];
+
+        const q = query({
+          prompt: 'Read test.txt and append an empty line to it.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            // Only allow read_file, list_directory should trigger canUseTool
+            coreTools: ['read_file', 'write_file'],
+            allowedTools: ['read_file'],
+            canUseTool: async (toolName) => {
+              canUseToolCalls.push(toolName);
+              return {
+                behavior: 'allow',
+                updatedInput: {},
+              };
+            },
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Both tools should have been executed
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+
+          // canUseTool should have been called for write_file (not in allowedTools)
+          // but NOT for read_file (in allowedTools)
+          expect(canUseToolCalls).toContain('write_file');
+          expect(canUseToolCalls).not.toContain('read_file');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should work with permissionMode: auto-edit',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const canUseToolCalls: string[] = [];
+
+        const q = query({
+          prompt: 'Read test.txt, write "new" to it, and list the directory.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'auto-edit',
+            // Allow list_directory in addition to auto-approved edit tools
+            allowedTools: ['list_directory'],
+            canUseTool: async (toolName) => {
+              canUseToolCalls.push(toolName);
+              return {
+                behavior: 'deny',
+                message: 'Should not be called',
+              };
+            },
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // All tools should have been executed
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+          expect(toolNames).toContain('list_directory');
+
+          // canUseTool should NOT have been called
+          // (edit tools auto-approved, list_directory in allowedTools)
+          expect(canUseToolCalls.length).toBe(0);
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+  });
+
+  describe('Combined tool control scenarios', () => {
+    it(
+      'should work with coreTools + allowedTools',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const q = query({
+          prompt: 'Read test.txt and write "modified" to it.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            // Limit to specific tools
+            coreTools: ['read_file', 'write_file', 'list_directory'],
+            // Auto-approve write operations
+            allowedTools: ['write_file'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should use allowed tools from coreTools
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+
+          // Should NOT use tools outside coreTools
+          expect(toolNames).not.toContain('run_shell_command');
+
+          // Verify file was modified
+          const content = await helper.readFile('test.txt');
+          expect(content).toContain('modified');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should work with coreTools + excludeTools',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const q = query({
+          prompt:
+            'Read test.txt, write "new content" to it, and list directory.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Allow file operations
+            coreTools: ['read_file', 'write_file', 'edit', 'list_directory'],
+            // But exclude edit
+            excludeTools: ['edit'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should use non-excluded tools from coreTools
+          expect(toolNames).toContain('read_file');
+
+          // Should NOT use excluded tool
+          expect(toolNames).not.toContain('edit');
+
+          // File should still exist
+          expect(helper.fileExists('test.txt')).toBe(true);
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should work with all three parameters together',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const canUseToolCalls: string[] = [];
+
+        const q = query({
+          prompt:
+            'Read test.txt, write "modified" to it, and list the directory.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'default',
+            // Limit available tools
+            coreTools: ['read_file', 'write_file', 'list_directory', 'edit'],
+            // Block edit
+            excludeTools: ['edit'],
+            // Auto-approve write
+            allowedTools: ['write_file'],
+            canUseTool: async (toolName) => {
+              canUseToolCalls.push(toolName);
+              return {
+                behavior: 'allow',
+                updatedInput: {},
+              };
+            },
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should use allowed tools
+          expect(toolNames).toContain('read_file');
+          expect(toolNames).toContain('write_file');
+
+          // Should NOT use excluded tool
+          expect(toolNames).not.toContain('edit');
+
+          // canUseTool should be called for tools not in allowedTools
+          // but should NOT be called for write_file (in allowedTools)
+          expect(canUseToolCalls).not.toContain('write_file');
+
+          // Verify file was modified
+          const content = await helper.readFile('test.txt');
+          expect(content).toContain('modified');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+  });
+
+  describe('Edge cases and error handling', () => {
+    it(
+      'should handle non-existent tool names in excludeTools',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const q = query({
+          prompt: 'Read test.txt.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Non-existent tool names should be ignored
+            excludeTools: ['non_existent_tool', 'another_fake_tool'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should work normally
+          expect(toolNames).toContain('read_file');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+
+    it(
+      'should handle non-existent tool names in allowedTools',
+      async () => {
+        await helper.createFile('test.txt', 'test');
+
+        const q = query({
+          prompt: 'Read test.txt.',
+          options: {
+            ...SHARED_TEST_OPTIONS,
+            cwd: testDir,
+            permissionMode: 'yolo',
+            // Non-existent tool names should be ignored
+            allowedTools: ['non_existent_tool', 'read_file'],
+            debug: false,
+          },
+        });
+
+        const messages: SDKMessage[] = [];
+
+        try {
+          for await (const message of q) {
+            messages.push(message);
+          }
+
+          const toolCalls = findToolCalls(messages);
+          const toolNames = toolCalls.map((tc) => tc.toolUse.name);
+
+          // Should work normally
+          expect(toolNames).toContain('read_file');
+        } finally {
+          await q.close();
+        }
+      },
+      TEST_TIMEOUT,
+    );
+  });
+});

integration-tests/simple-mcp-server.test.ts

@@ -213,7 +213,7 @@ describe('simple-mcp-server', () => {
   it('should add two numbers', async () => {
     // Test directory is already set up in before hook
     // Just run the command - MCP server config is in settings.json
-    const output = await rig.run('add 5 and 10');
+    const output = await rig.run('add 5 and 10, use tool if you can.');
 
     const foundToolCall = await rig.waitForToolCall('add');
 

integration-tests/tsconfig.json

@@ -2,7 +2,13 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "allowJs": true
+    "allowJs": true,
+    "baseUrl": ".",
+    "paths": {
+      "@qwen-code/sdk-typescript": [
+        "../packages/sdk-typescript/dist/index.d.ts"
+      ]
+    }
   },
   "include": ["**/*.ts"],
   "references": [{ "path": "../packages/core" }]

integration-tests/vitest.config.ts

@@ -1,12 +1,15 @@
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2025 Qwen Team
  * SPDX-License-Identifier: Apache-2.0
  */
 
 import { defineConfig } from 'vitest/config';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const timeoutMinutes = Number(process.env.TB_TIMEOUT_MINUTES || '5');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const timeoutMinutes = Number(process.env['TB_TIMEOUT_MINUTES'] || '5');
 const testTimeoutMs = timeoutMinutes * 60 * 1000;
 
 export default defineConfig({
@@ -25,4 +28,13 @@ export default defineConfig({
       },
     },
   },
+  resolve: {
+    alias: {
+      // Use built SDK bundle for e2e tests
+      '@qwen-code/sdk-typescript': resolve(
+        __dirname,
+        '../packages/sdk-typescript/dist/index.mjs',
+      ),
+    },
+  },
 });

packages/cli/src/config/config.ts

@@ -6,6 +6,7 @@
 
 import {
   ApprovalMode,
+  AuthType,
   Config,
   DEFAULT_QWEN_EMBEDDING_MODEL,
   DEFAULT_MEMORY_FILE_FILTERING_OPTIONS,
@@ -133,6 +134,10 @@ export interface CliArgs {
   continue: boolean | undefined;
   /** Resume a specific session by its ID */
   resume: string | undefined;
+  maxSessionTurns: number | undefined;
+  coreTools: string[] | undefined;
+  excludeTools: string[] | undefined;
+  authType: string | undefined;
 }
 
 function normalizeOutputFormat(
@@ -411,6 +416,36 @@ export async function parseArguments(settings: Settings): Promise<CliArgs> {
           description:
             'Resume a specific session by its ID. Use without an ID to show session picker.',
         })
+        .option('max-session-turns', {
+          type: 'number',
+          description: 'Maximum number of session turns',
+        })
+        .option('core-tools', {
+          type: 'array',
+          string: true,
+          description: 'Core tool paths',
+          coerce: (tools: string[]) =>
+            tools.flatMap((tool) => tool.split(',').map((t) => t.trim())),
+        })
+        .option('exclude-tools', {
+          type: 'array',
+          string: true,
+          description: 'Tools to exclude',
+          coerce: (tools: string[]) =>
+            tools.flatMap((tool) => tool.split(',').map((t) => t.trim())),
+        })
+        .option('allowed-tools', {
+          type: 'array',
+          string: true,
+          description: 'Tools to allow, will bypass confirmation',
+          coerce: (tools: string[]) =>
+            tools.flatMap((tool) => tool.split(',').map((t) => t.trim())),
+        })
+        .option('auth-type', {
+          type: 'string',
+          choices: [AuthType.USE_OPENAI, AuthType.QWEN_OAUTH],
+          description: 'Authentication type',
+        })
         .deprecateOption(
           'show-memory-usage',
           'Use the "ui.showMemoryUsage" setting in settings.json instead. This flag will be removed in a future version.',
@@ -745,8 +780,14 @@ export async function loadCliConfig(
     interactive = false;
   }
   // In non-interactive mode, exclude tools that require a prompt.
+  // However, if stream-json input is used, control can be requested via JSON messages,
+  // so tools should not be excluded in that case.
   const extraExcludes: string[] = [];
-  if (!interactive && !argv.experimentalAcp) {
+  if (
+    !interactive &&
+    !argv.experimentalAcp &&
+    inputFormat !== InputFormat.STREAM_JSON
+  ) {
     switch (approvalMode) {
       case ApprovalMode.PLAN:
       case ApprovalMode.DEFAULT:
@@ -770,6 +811,7 @@ export async function loadCliConfig(
     settings,
     activeExtensions,
     extraExcludes.length > 0 ? extraExcludes : undefined,
+    argv.excludeTools,
   );
   const blockedMcpServers: Array<{ name: string; extensionName: string }> = [];
 
@@ -850,7 +892,7 @@ export async function loadCliConfig(
     debugMode,
     question,
     fullContext: argv.allFiles || false,
-    coreTools: settings.tools?.core || undefined,
+    coreTools: argv.coreTools || settings.tools?.core || undefined,
     allowedTools: argv.allowedTools || settings.tools?.allowed || undefined,
     excludeTools,
     toolDiscoveryCommand: settings.tools?.discoveryCommand,
@@ -883,13 +925,16 @@ export async function loadCliConfig(
     model: resolvedModel,
     extensionContextFilePaths,
     sessionTokenLimit: settings.model?.sessionTokenLimit ?? -1,
-    maxSessionTurns: settings.model?.maxSessionTurns ?? -1,
+    maxSessionTurns:
+      argv.maxSessionTurns ?? settings.model?.maxSessionTurns ?? -1,
     experimentalZedIntegration: argv.experimentalAcp || false,
     listExtensions: argv.listExtensions || false,
     extensions: allExtensions,
     blockedMcpServers,
     noBrowser: !!process.env['NO_BROWSER'],
-    authType: settings.security?.auth?.selectedType,
+    authType:
+      (argv.authType as AuthType | undefined) ||
+      settings.security?.auth?.selectedType,
     inputFormat,
     outputFormat,
     includePartialMessages,
@@ -997,8 +1042,10 @@ function mergeExcludeTools(
   settings: Settings,
   extensions: Extension[],
   extraExcludes?: string[] | undefined,
+  cliExcludeTools?: string[] | undefined,
 ): string[] {
   const allExcludeTools = new Set([
+    ...(cliExcludeTools || []),
     ...(settings.tools?.exclude || []),
     ...(extraExcludes || []),
   ]);

packages/cli/src/gemini.test.tsx

@@ -481,6 +481,10 @@ describe('gemini.tsx main function kitty protocol', () => {
       includePartialMessages: undefined,
       continue: undefined,
       resume: undefined,
+      coreTools: undefined,
+      excludeTools: undefined,
+      authType: undefined,
+      maxSessionTurns: undefined,
     });
 
     await main();

packages/cli/src/gemini.tsx

@@ -383,7 +383,18 @@ export async function main() {
 
     setMaxSizedBoxDebugging(isDebugMode);
 
-    const initializationResult = await initializeApp(config, settings);
+    // Check input format early to determine initialization flow
+    const inputFormat =
+      typeof config.getInputFormat === 'function'
+        ? config.getInputFormat()
+        : InputFormat.TEXT;
+
+    // For stream-json mode, defer config.initialize() until after the initialize control request
+    // For other modes, initialize normally
+    let initializationResult: InitializationResult | undefined;
+    if (inputFormat !== InputFormat.STREAM_JSON) {
+      initializationResult = await initializeApp(config, settings);
+    }
 
     if (
       settings.merged.security?.auth?.selectedType ===
@@ -417,19 +428,15 @@ export async function main() {
         settings,
         startupWarnings,
         process.cwd(),
-        initializationResult,
+        initializationResult!,
       );
       return;
     }
 
-    await config.initialize();
-
-    // Check input format BEFORE reading stdin
-    // In STREAM_JSON mode, stdin should be left for StreamJsonInputReader
-    const inputFormat =
-      typeof config.getInputFormat === 'function'
-        ? config.getInputFormat()
-        : InputFormat.TEXT;
+    // For non-stream-json mode, initialize config here
+    if (inputFormat !== InputFormat.STREAM_JSON) {
+      await config.initialize();
+    }
 
     // Only read stdin if NOT in stream-json mode
     // In stream-json mode, stdin is used for protocol messages (control requests, etc.)
@@ -442,7 +449,8 @@ export async function main() {
     }
 
     const nonInteractiveConfig = await validateNonInteractiveAuth(
-      settings.merged.security?.auth?.selectedType,
+      (argv.authType as AuthType) ||
+        settings.merged.security?.auth?.selectedType,
       settings.merged.security?.auth?.useExternal,
       config,
       settings,

packages/cli/src/i18n/locales/en.js

@@ -110,7 +110,6 @@ export default {
     'open full Qwen Code documentation in your browser',
   'Configuration not available.': 'Configuration not available.',
   'change the auth method': 'change the auth method',
-  'Show quit confirmation dialog': 'Show quit confirmation dialog',
   'Copy the last result or code snippet to clipboard':
     'Copy the last result or code snippet to clipboard',
 
@@ -690,18 +689,6 @@ export default {
   'A custom command wants to run the following shell commands:':
     'A custom command wants to run the following shell commands:',
 
-  // ============================================================================
-  // Dialogs - Quit Confirmation
-  // ============================================================================
-  'What would you like to do before exiting?':
-    'What would you like to do before exiting?',
-  'Quit immediately (/quit)': 'Quit immediately (/quit)',
-  'Generate summary and quit (/summary)':
-    'Generate summary and quit (/summary)',
-  'Save conversation and quit (/chat save)':
-    'Save conversation and quit (/chat save)',
-  'Cancel (stay in application)': 'Cancel (stay in application)',
-
   // ============================================================================
   // Dialogs - Pro Quota
   // ============================================================================

packages/cli/src/i18n/locales/zh.js

@@ -108,7 +108,6 @@ export default {
     '在浏览器中打开完整的 Qwen Code 文档',
   'Configuration not available.': '配置不可用',
   'change the auth method': '更改认证方法',
-  'Show quit confirmation dialog': '显示退出确认对话框',
   'Copy the last result or code snippet to clipboard':
     '将最后的结果或代码片段复制到剪贴板',
 
@@ -655,15 +654,6 @@ export default {
   'A custom command wants to run the following shell commands:':
     '自定义命令想要运行以下 shell 命令：',
 
-  // ============================================================================
-  // Dialogs - Quit Confirmation
-  // ============================================================================
-  'What would you like to do before exiting?': '退出前您想要做什么？',
-  'Quit immediately (/quit)': '立即退出 (/quit)',
-  'Generate summary and quit (/summary)': '生成摘要并退出 (/summary)',
-  'Save conversation and quit (/chat save)': '保存对话并退出 (/chat save)',
-  'Cancel (stay in application)': '取消（留在应用程序中）',
-
   // ============================================================================
   // Dialogs - Pro Quota
   // ============================================================================

packages/cli/src/nonInteractive/control/ControlDispatcher.ts

@@ -26,7 +26,7 @@
 import type { IControlContext } from './ControlContext.js';
 import type { IPendingRequestRegistry } from './controllers/baseController.js';
 import { SystemController } from './controllers/systemController.js';
-// import { PermissionController } from './controllers/permissionController.js';
+import { PermissionController } from './controllers/permissionController.js';
 // import { MCPController } from './controllers/mcpController.js';
 // import { HookController } from './controllers/hookController.js';
 import type {
@@ -64,7 +64,7 @@ export class ControlDispatcher implements IPendingRequestRegistry {
 
   // Make controllers publicly accessible
   readonly systemController: SystemController;
-  // readonly permissionController: PermissionController;
+  readonly permissionController: PermissionController;
   // readonly mcpController: MCPController;
   // readonly hookController: HookController;
 
@@ -83,11 +83,11 @@ export class ControlDispatcher implements IPendingRequestRegistry {
       this,
       'SystemController',
     );
-    // this.permissionController = new PermissionController(
-    //   context,
-    //   this,
-    //   'PermissionController',
-    // );
+    this.permissionController = new PermissionController(
+      context,
+      this,
+      'PermissionController',
+    );
     // this.mcpController = new MCPController(context, this, 'MCPController');
     // this.hookController = new HookController(context, this, 'HookController');
 
@@ -230,7 +230,7 @@ export class ControlDispatcher implements IPendingRequestRegistry {
 
     // Cleanup controllers (MCP controller will close all clients)
     this.systemController.cleanup();
-    // this.permissionController.cleanup();
+    this.permissionController.cleanup();
     // this.mcpController.cleanup();
     // this.hookController.cleanup();
   }
@@ -302,9 +302,9 @@ export class ControlDispatcher implements IPendingRequestRegistry {
       case 'supported_commands':
         return this.systemController;
 
-      // case 'can_use_tool':
-      // case 'set_permission_mode':
-      //   return this.permissionController;
+      case 'can_use_tool':
+      case 'set_permission_mode':
+        return this.permissionController;
 
       // case 'mcp_message':
       // case 'mcp_server_status':

packages/cli/src/nonInteractive/control/ControlService.ts

@@ -29,7 +29,7 @@
 import type { IControlContext } from './ControlContext.js';
 import type { ControlDispatcher } from './ControlDispatcher.js';
 import type {
-  // PermissionServiceAPI,
+  PermissionServiceAPI,
   SystemServiceAPI,
   // McpServiceAPI,
   // HookServiceAPI,
@@ -61,43 +61,31 @@ export class ControlService {
    * Handles tool execution permissions, approval checks, and callbacks.
    * Delegates to the shared PermissionController instance.
    */
-  // get permission(): PermissionServiceAPI {
-  //   const controller = this.dispatcher.permissionController;
-  //   return {
-  //     /**
-  //      * Check if a tool should be allowed based on current permission settings
-  //      *
-  //      * Evaluates permission mode and tool registry to determine if execution
-  //      * should proceed. Can optionally modify tool arguments based on confirmation details.
-  //      *
-  //      * @param toolRequest - Tool call request information
-  //      * @param confirmationDetails - Optional confirmation details for UI
-  //      * @returns Permission decision with optional updated arguments
-  //      */
-  //     shouldAllowTool: controller.shouldAllowTool.bind(controller),
-  //
-  //     /**
-  //      * Build UI suggestions for tool confirmation dialogs
-  //      *
-  //      * Creates actionable permission suggestions based on tool confirmation details.
-  //      *
-  //      * @param confirmationDetails - Tool confirmation details
-  //      * @returns Array of permission suggestions or null
-  //      */
-  //     buildPermissionSuggestions:
-  //       controller.buildPermissionSuggestions.bind(controller),
-  //
-  //     /**
-  //      * Get callback for monitoring tool call status updates
-  //      *
-  //      * Returns callback function for integration with CoreToolScheduler.
-  //      *
-  //      * @returns Callback function for tool call updates
-  //      */
-  //     getToolCallUpdateCallback:
-  //       controller.getToolCallUpdateCallback.bind(controller),
-  //   };
-  // }
+  get permission(): PermissionServiceAPI {
+    const controller = this.dispatcher.permissionController;
+    return {
+      /**
+       * Build UI suggestions for tool confirmation dialogs
+       *
+       * Creates actionable permission suggestions based on tool confirmation details.
+       *
+       * @param confirmationDetails - Tool confirmation details
+       * @returns Array of permission suggestions or null
+       */
+      buildPermissionSuggestions:
+        controller.buildPermissionSuggestions.bind(controller),
+
+      /**
+       * Get callback for monitoring tool call status updates
+       *
+       * Returns callback function for integration with CoreToolScheduler.
+       *
+       * @returns Callback function for tool call updates
+       */
+      getToolCallUpdateCallback:
+        controller.getToolCallUpdateCallback.bind(controller),
+    };
+  }
 
   /**
    * System Domain API

packages/cli/src/nonInteractive/control/controllers/baseController.ts

@@ -174,7 +174,5 @@ export abstract class BaseController {
   /**
    * Cleanup resources
    */
-  cleanup(): void {
-    // Subclasses can override to add cleanup logic
-  }
+  cleanup(): void {}
 }

packages/cli/src/nonInteractive/control/controllers/permissionController.ts

@@ -15,8 +15,10 @@
  */
 
 import type {
-  ToolCallRequestInfo,
   WaitingToolCall,
+  ToolExecuteConfirmationDetails,
+  ToolMcpConfirmationDetails,
+  ApprovalMode,
 } from '@qwen-code/qwen-code-core';
 import {
   InputFormat,
@@ -206,6 +208,7 @@ export class PermissionController extends BaseController {
     }
 
     this.context.permissionMode = mode;
+    this.context.config.setApprovalMode(mode as ApprovalMode);
 
     if (this.context.debugMode) {
       console.error(
@@ -334,47 +337,6 @@ export class PermissionController extends BaseController {
     }
   }
 
-  /**
-   * Check if a tool should be executed based on current permission settings
-   *
-   * This is a convenience method for direct tool execution checks without
-   * going through the control request flow.
-   */
-  async shouldAllowTool(
-    toolRequest: ToolCallRequestInfo,
-    confirmationDetails?: unknown,
-  ): Promise<{
-    allowed: boolean;
-    message?: string;
-    updatedArgs?: Record<string, unknown>;
-  }> {
-    // Check permission mode
-    const modeResult = this.checkPermissionMode();
-    if (!modeResult.allowed) {
-      return {
-        allowed: false,
-        message: modeResult.message,
-      };
-    }
-
-    // Check tool registry
-    const registryResult = this.checkToolRegistry(toolRequest.name);
-    if (!registryResult.allowed) {
-      return {
-        allowed: false,
-        message: registryResult.message,
-      };
-    }
-
-    // If we have confirmation details, we could potentially modify args
-    // This is a hook for future enhancement
-    if (confirmationDetails) {
-      // Future: handle argument modifications based on confirmation details
-    }
-
-    return { allowed: true };
-  }
-
   /**
    * Get callback for monitoring tool calls and handling outgoing permission requests
    * This is passed to executeToolCall to hook into CoreToolScheduler updates
@@ -430,17 +392,14 @@ export class PermissionController extends BaseController {
         toolCall.confirmationDetails,
       );
 
-      const response = await this.sendControlRequest(
-        {
-          subtype: 'can_use_tool',
-          tool_name: toolCall.request.name,
-          tool_use_id: toolCall.request.callId,
-          input: toolCall.request.args,
-          permission_suggestions: permissionSuggestions,
-          blocked_path: null,
-        } as CLIControlPermissionRequest,
-        30000,
-      );
+      const response = await this.sendControlRequest({
+        subtype: 'can_use_tool',
+        tool_name: toolCall.request.name,
+        tool_use_id: toolCall.request.callId,
+        input: toolCall.request.args,
+        permission_suggestions: permissionSuggestions,
+        blocked_path: null,
+      } as CLIControlPermissionRequest);
 
       if (response.subtype !== 'success') {
         await toolCall.confirmationDetails.onConfirm(
@@ -462,8 +421,15 @@ export class PermissionController extends BaseController {
           ToolConfirmationOutcome.ProceedOnce,
         );
       } else {
+        // Extract cancel message from response if available
+        const cancelMessage =
+          typeof payload['message'] === 'string'
+            ? payload['message']
+            : undefined;
+
         await toolCall.confirmationDetails.onConfirm(
           ToolConfirmationOutcome.Cancel,
+          cancelMessage ? { cancelMessage } : undefined,
         );
       }
     } catch (error) {
@@ -473,9 +439,23 @@ export class PermissionController extends BaseController {
           error,
         );
       }
-      await toolCall.confirmationDetails.onConfirm(
-        ToolConfirmationOutcome.Cancel,
-      );
+      // On error, use default cancel message
+      // Only pass payload for exec and mcp types that support it
+      const confirmationType = toolCall.confirmationDetails.type;
+      if (['edit', 'exec', 'mcp'].includes(confirmationType)) {
+        const execOrMcpDetails = toolCall.confirmationDetails as
+          | ToolExecuteConfirmationDetails
+          | ToolMcpConfirmationDetails;
+        await execOrMcpDetails.onConfirm(
+          ToolConfirmationOutcome.Cancel,
+          undefined,
+        );
+      } else {
+        // For other types, don't pass payload (backward compatible)
+        await toolCall.confirmationDetails.onConfirm(
+          ToolConfirmationOutcome.Cancel,
+        );
+      }
     } finally {
       this.pendingOutgoingRequests.delete(toolCall.request.callId);
     }

packages/cli/src/nonInteractive/control/controllers/systemController.ts

@@ -19,6 +19,8 @@ import type {
   CLIControlInitializeRequest,
   CLIControlSetModelRequest,
 } from '../../types.js';
+import { CommandService } from '../../../services/CommandService.js';
+import { BuiltinCommandLoader } from '../../../services/BuiltinCommandLoader.js';
 
 export class SystemController extends BaseController {
   /**
@@ -54,11 +56,62 @@ export class SystemController extends BaseController {
   private async handleInitialize(
     payload: CLIControlInitializeRequest,
   ): Promise<Record<string, unknown>> {
-    // Register SDK MCP servers if provided
-    if (payload.sdkMcpServers && Array.isArray(payload.sdkMcpServers)) {
-      for (const serverName of payload.sdkMcpServers) {
+    this.context.config.setSdkMode(true);
+
+    if (payload.sdkMcpServers && typeof payload.sdkMcpServers === 'object') {
+      for (const serverName of Object.keys(payload.sdkMcpServers)) {
         this.context.sdkMcpServers.add(serverName);
       }
+
+      try {
+        this.context.config.addMcpServers(payload.sdkMcpServers);
+        if (this.context.debugMode) {
+          console.error(
+            `[SystemController] Added ${Object.keys(payload.sdkMcpServers).length} SDK MCP servers to config`,
+          );
+        }
+      } catch (error) {
+        if (this.context.debugMode) {
+          console.error(
+            '[SystemController] Failed to add SDK MCP servers:',
+            error,
+          );
+        }
+      }
+    }
+
+    if (payload.mcpServers && typeof payload.mcpServers === 'object') {
+      try {
+        this.context.config.addMcpServers(payload.mcpServers);
+        if (this.context.debugMode) {
+          console.error(
+            `[SystemController] Added ${Object.keys(payload.mcpServers).length} MCP servers to config`,
+          );
+        }
+      } catch (error) {
+        if (this.context.debugMode) {
+          console.error('[SystemController] Failed to add MCP servers:', error);
+        }
+      }
+    }
+
+    if (payload.agents && Array.isArray(payload.agents)) {
+      try {
+        this.context.config.setSessionSubagents(payload.agents);
+
+        if (this.context.debugMode) {
+          console.error(
+            `[SystemController] Added ${payload.agents.length} session subagents to config`,
+          );
+        }
+      } catch (error) {
+        if (this.context.debugMode) {
+          console.error(
+            '[SystemController] Failed to add session subagents:',
+            error,
+          );
+        }
+      }
     }
 
     // Build capabilities for response
@@ -86,35 +139,14 @@ export class SystemController extends BaseController {
   buildControlCapabilities(): Record<string, unknown> {
     const capabilities: Record<string, unknown> = {
       can_handle_can_use_tool: true,
-      can_handle_hook_callback: true,
+      can_handle_hook_callback: false,
       can_set_permission_mode:
         typeof this.context.config.setApprovalMode === 'function',
       can_set_model: typeof this.context.config.setModel === 'function',
+      /* TODO: sdkMcpServers support */
+      can_handle_mcp_message: false,
     };
 
-    // Check if MCP message handling is available
-    try {
-      const mcpProvider = this.context.config as unknown as {
-        getMcpServers?: () => Record<string, unknown> | undefined;
-      };
-      if (typeof mcpProvider.getMcpServers === 'function') {
-        const servers = mcpProvider.getMcpServers();
-        capabilities['can_handle_mcp_message'] = Boolean(
-          servers && Object.keys(servers).length > 0,
-        );
-      } else {
-        capabilities['can_handle_mcp_message'] = false;
-      }
-    } catch (error) {
-      if (this.context.debugMode) {
-        console.error(
-          '[SystemController] Failed to determine MCP capability:',
-          error,
-        );
-      }
-      capabilities['can_handle_mcp_message'] = false;
-    }
-
     return capabilities;
   }
 
@@ -189,27 +221,45 @@ export class SystemController extends BaseController {
   /**
    * Handle supported_commands request
    *
-   * Returns list of supported control commands
-   *
-   * Note: This list should match the ControlRequestType enum in
-   * packages/sdk/typescript/src/types/controlRequests.ts
+   * Returns list of supported slash commands loaded dynamically
    */
   private async handleSupportedCommands(): Promise<Record<string, unknown>> {
-    const commands = [
-      'initialize',
-      'interrupt',
-      'set_model',
-      'supported_commands',
-      'can_use_tool',
-      'set_permission_mode',
-      'mcp_message',
-      'mcp_server_status',
-      'hook_callback',
-    ];
+    const slashCommands = await this.loadSlashCommandNames();
 
     return {
       subtype: 'supported_commands',
-      commands,
+      commands: slashCommands,
     };
   }
+
+  /**
+   * Load slash command names using CommandService
+   *
+   * @returns Promise resolving to array of slash command names
+   */
+  private async loadSlashCommandNames(): Promise<string[]> {
+    const controller = new AbortController();
+    try {
+      const service = await CommandService.create(
+        [new BuiltinCommandLoader(this.context.config)],
+        controller.signal,
+      );
+      const names = new Set<string>();
+      const commands = service.getCommands();
+      for (const command of commands) {
+        names.add(command.name);
+      }
+      return Array.from(names).sort();
+    } catch (error) {
+      if (this.context.debugMode) {
+        console.error(
+          '[SystemController] Failed to load slash commands:',
+          error,
+        );
+      }
+      return [];
+    } finally {
+      controller.abort();
+    }
+  }
 }

packages/cli/src/nonInteractive/control/types/serviceAPIs.ts

@@ -13,10 +13,7 @@
  */
 
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type {
-  ToolCallRequestInfo,
-  MCPServerConfig,
-} from '@qwen-code/qwen-code-core';
+import type { MCPServerConfig } from '@qwen-code/qwen-code-core';
 import type { PermissionSuggestion } from '../../types.js';
 
 /**
@@ -26,25 +23,6 @@ import type { PermissionSuggestion } from '../../types.js';
  * permission suggestions, and tool call monitoring callbacks.
  */
 export interface PermissionServiceAPI {
-  /**
-   * Check if a tool should be allowed based on current permission settings
-   *
-   * Evaluates permission mode and tool registry to determine if execution
-   * should proceed. Can optionally modify tool arguments based on confirmation details.
-   *
-   * @param toolRequest - Tool call request information containing name, args, and call ID
-   * @param confirmationDetails - Optional confirmation details for UI-driven approvals
-   * @returns Promise resolving to permission decision with optional updated arguments
-   */
-  shouldAllowTool(
-    toolRequest: ToolCallRequestInfo,
-    confirmationDetails?: unknown,
-  ): Promise<{
-    allowed: boolean;
-    message?: string;
-    updatedArgs?: Record<string, unknown>;
-  }>;
-
   /**
    * Build UI suggestions for tool confirmation dialogs
    *

packages/cli/src/nonInteractive/io/BaseJsonOutputAdapter.ts

@@ -13,7 +13,11 @@ import type {
   ServerGeminiStreamEvent,
   TaskResultDisplay,
 } from '@qwen-code/qwen-code-core';
-import { GeminiEventType, ToolErrorType } from '@qwen-code/qwen-code-core';
+import {
+  GeminiEventType,
+  ToolErrorType,
+  parseAndFormatApiError,
+} from '@qwen-code/qwen-code-core';
 import type { Part, GenerateContentResponseUsageMetadata } from '@google/genai';
 import type {
   CLIAssistantMessage,
@@ -600,6 +604,18 @@ export abstract class BaseJsonOutputAdapter {
         }
         this.finalizePendingBlocks(state, null);
         break;
+      case GeminiEventType.Error: {
+        // Format the error message using parseAndFormatApiError for consistency
+        // with interactive mode error display
+        const errorText = parseAndFormatApiError(
+          event.value.error,
+          this.config.getContentGeneratorConfig()?.authType,
+          undefined,
+          this.config.getModel(),
+        );
+        this.appendText(state, errorText, null);
+        break;
+      }
       default:
         break;
     }
@@ -939,9 +955,25 @@ export abstract class BaseJsonOutputAdapter {
     this.emitMessageImpl(message);
   }
 
+  /**
+   * Checks if responseParts contain any functionResponse with an error.
+   * This handles cancelled responses and other error cases where the error
+   * is embedded in responseParts rather than the top-level error field.
+   * @param responseParts - Array of Part objects
+   * @returns Error message if found, undefined otherwise
+   */
+  private checkResponsePartsForError(
+    responseParts: Part[] | undefined,
+  ): string | undefined {
+    // Use the shared helper function defined at file level
+    return checkResponsePartsForError(responseParts);
+  }
+
   /**
    * Emits a tool result message.
    * Collects execution denied tool calls for inclusion in result messages.
+   * Handles both explicit errors (response.error) and errors embedded in
+   * responseParts (e.g., cancelled responses).
    * @param request - Tool call request info
    * @param response - Tool call response info
    * @param parentToolUseId - Parent tool use ID (null for main agent)
@@ -951,6 +983,14 @@ export abstract class BaseJsonOutputAdapter {
     response: ToolCallResponseInfo,
     parentToolUseId: string | null = null,
   ): void {
+    // Check for errors in responseParts (e.g., cancelled responses)
+    const responsePartsError = this.checkResponsePartsForError(
+      response.responseParts,
+    );
+
+    // Determine if this is an error response
+    const hasError = Boolean(response.error) || Boolean(responsePartsError);
+
     // Track permission denials (execution denied errors)
     if (
       response.error &&
@@ -967,7 +1007,7 @@ export abstract class BaseJsonOutputAdapter {
     const block: ToolResultBlock = {
       type: 'tool_result',
       tool_use_id: request.callId,
-      is_error: Boolean(response.error),
+      is_error: hasError,
     };
     const content = toolResultContent(response);
     if (content !== undefined) {
@@ -1173,11 +1213,41 @@ export function partsToString(parts: Part[]): string {
     .join('');
 }
 
+/**
+ * Checks if responseParts contain any functionResponse with an error.
+ * Helper function for extracting error messages from responseParts.
+ * @param responseParts - Array of Part objects
+ * @returns Error message if found, undefined otherwise
+ */
+function checkResponsePartsForError(
+  responseParts: Part[] | undefined,
+): string | undefined {
+  if (!responseParts || responseParts.length === 0) {
+    return undefined;
+  }
+
+  for (const part of responseParts) {
+    if (
+      'functionResponse' in part &&
+      part.functionResponse?.response &&
+      typeof part.functionResponse.response === 'object' &&
+      'error' in part.functionResponse.response &&
+      part.functionResponse.response['error']
+    ) {
+      const error = part.functionResponse.response['error'];
+      return typeof error === 'string' ? error : String(error);
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * Extracts content from tool response.
  * Uses functionResponsePartsToString to properly handle functionResponse parts,
  * which correctly extracts output content from functionResponse objects rather
  * than simply concatenating text or JSON.stringify.
+ * Also handles errors embedded in responseParts (e.g., cancelled responses).
  *
  * @param response - Tool call response
  * @returns String content or undefined
@@ -1188,6 +1258,11 @@ export function toolResultContent(
   if (response.error) {
     return response.error.message;
   }
+  // Check for errors in responseParts (e.g., cancelled responses)
+  const responsePartsError = checkResponsePartsForError(response.responseParts);
+  if (responsePartsError) {
+    return responsePartsError;
+  }
   if (
     typeof response.resultDisplay === 'string' &&
     response.resultDisplay.trim().length > 0

packages/cli/src/nonInteractive/session.test.ts

@@ -69,6 +69,7 @@ function createConfig(overrides: ConfigOverrides = {}): Config {
     getDebugMode: () => false,
     getApprovalMode: () => 'auto',
     getOutputFormat: () => 'stream-json',
+    initialize: vi.fn(),
   };
   return { ...base, ...overrides } as unknown as Config;
 }

packages/cli/src/nonInteractive/session.ts

@@ -4,17 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * Stream JSON Runner with Session State Machine
- *
- * Handles stream-json input/output format with:
- * - Initialize handshake
- * - Message routing (control vs user messages)
- * - FIFO user message queue
- * - Sequential message processing
- * - Graceful shutdown
- */
-
 import type { Config } from '@qwen-code/qwen-code-core';
 import { StreamJsonInputReader } from './io/StreamJsonInputReader.js';
 import { StreamJsonOutputAdapter } from './io/StreamJsonOutputAdapter.js';
@@ -42,48 +31,7 @@ import { createMinimalSettings } from '../config/settings.js';
 import { runNonInteractive } from '../nonInteractiveCli.js';
 import { ConsolePatcher } from '../ui/utils/ConsolePatcher.js';
 
-const SESSION_STATE = {
-  INITIALIZING: 'initializing',
-  IDLE: 'idle',
-  PROCESSING_QUERY: 'processing_query',
-  SHUTTING_DOWN: 'shutting_down',
-} as const;
-
-type SessionState = (typeof SESSION_STATE)[keyof typeof SESSION_STATE];
-
-/**
- * Message type classification for routing
- */
-type MessageType =
-  | 'control_request'
-  | 'control_response'
-  | 'control_cancel'
-  | 'user'
-  | 'assistant'
-  | 'system'
-  | 'result'
-  | 'stream_event'
-  | 'unknown';
-
-/**
- * Routed message with classification
- */
-interface RoutedMessage {
-  type: MessageType;
-  message:
-    | CLIMessage
-    | CLIControlRequest
-    | CLIControlResponse
-    | ControlCancelRequest;
-}
-
-/**
- * Session Manager
- *
- * Manages the session lifecycle and message processing state machine.
- */
-class SessionManager {
-  private state: SessionState = SESSION_STATE.INITIALIZING;
+class Session {
   private userMessageQueue: CLIUserMessage[] = [];
   private abortController: AbortController;
   private config: Config;
@@ -98,6 +46,9 @@ class SessionManager {
   private debugMode: boolean;
   private shutdownHandler: (() => void) | null = null;
   private initialPrompt: CLIUserMessage | null = null;
+  private processingPromise: Promise<void> | null = null;
+  private isShuttingDown: boolean = false;
+  private configInitialized: boolean = false;
 
   constructor(config: Config, initialPrompt?: CLIUserMessage) {
     this.config = config;
@@ -112,146 +63,31 @@ class SessionManager {
       config.getIncludePartialMessages(),
     );
 
-    // Setup signal handlers for graceful shutdown
     this.setupSignalHandlers();
   }
 
-  /**
-   * Get next prompt ID
-   */
   private getNextPromptId(): string {
     this.promptIdCounter++;
     return `${this.sessionId}########${this.promptIdCounter}`;
   }
 
-  /**
-   * Route a message to the appropriate handler based on its type
-   *
-   * Classifies incoming messages and routes them to appropriate handlers.
-   */
-  private route(
-    message:
-      | CLIMessage
-      | CLIControlRequest
-      | CLIControlResponse
-      | ControlCancelRequest,
-  ): RoutedMessage {
-    // Check control messages first
-    if (isControlRequest(message)) {
-      return { type: 'control_request', message };
-    }
-    if (isControlResponse(message)) {
-      return { type: 'control_response', message };
-    }
-    if (isControlCancel(message)) {
-      return { type: 'control_cancel', message };
+  private async ensureConfigInitialized(): Promise<void> {
+    if (this.configInitialized) {
+      return;
     }
 
-    // Check data messages
-    if (isCLIUserMessage(message)) {
-      return { type: 'user', message };
-    }
-    if (isCLIAssistantMessage(message)) {
-      return { type: 'assistant', message };
-    }
-    if (isCLISystemMessage(message)) {
-      return { type: 'system', message };
-    }
-    if (isCLIResultMessage(message)) {
-      return { type: 'result', message };
-    }
-    if (isCLIPartialAssistantMessage(message)) {
-      return { type: 'stream_event', message };
-    }
-
-    // Unknown message type
     if (this.debugMode) {
-      console.error(
-        '[SessionManager] Unknown message type:',
-        JSON.stringify(message, null, 2),
-      );
-    }
-    return { type: 'unknown', message };
-  }
-
-  /**
-   * Process a single message with unified logic for both initial prompt and stream messages.
-   *
-   * Handles:
-   * - Abort check
-   * - First message detection and handling
-   * - Normal message processing
-   * - Shutdown state checks
-   *
-   * @param message - Message to process
-   * @returns true if the calling code should exit (break/return), false to continue
-   */
-  private async processSingleMessage(
-    message:
-      | CLIMessage
-      | CLIControlRequest
-      | CLIControlResponse
-      | ControlCancelRequest,
-  ): Promise<boolean> {
-    // Check for abort
-    if (this.abortController.signal.aborted) {
-      return true;
+      console.error('[Session] Initializing config');
     }
 
-    // Handle first message if control system not yet initialized
-    if (this.controlSystemEnabled === null) {
-      const handled = await this.handleFirstMessage(message);
-      if (handled) {
-        // If handled, check if we should shutdown
-        return this.state === SESSION_STATE.SHUTTING_DOWN;
-      }
-      // If not handled, fall through to normal processing
-    }
-
-    // Process message normally
-    await this.processMessage(message);
-
-    // Check for shutdown after processing
-    return this.state === SESSION_STATE.SHUTTING_DOWN;
-  }
-
-  /**
-   * Main entry point - run the session
-   */
-  async run(): Promise<void> {
     try {
-      if (this.debugMode) {
-        console.error('[SessionManager] Starting session', this.sessionId);
-      }
-
-      // Process initial prompt if provided
-      if (this.initialPrompt !== null) {
-        const shouldExit = await this.processSingleMessage(this.initialPrompt);
-        if (shouldExit) {
-          await this.shutdown();
-          return;
-        }
-      }
-
-      // Process messages from stream
-      for await (const message of this.inputReader.read()) {
-        const shouldExit = await this.processSingleMessage(message);
-        if (shouldExit) {
-          break;
-        }
-      }
-
-      // Stream closed, shutdown
-      await this.shutdown();
+      await this.config.initialize();
+      this.configInitialized = true;
     } catch (error) {
       if (this.debugMode) {
-        console.error('[SessionManager] Error:', error);
+        console.error('[Session] Failed to initialize config:', error);
       }
-      await this.shutdown();
       throw error;
-    } finally {
-      // Ensure signal handlers are always cleaned up even if shutdown wasn't called
-      this.cleanupSignalHandlers();
     }
   }
 
@@ -259,14 +95,6 @@ class SessionManager {
     if (this.controlContext && this.dispatcher && this.controlService) {
       return;
     }
-    // The control system follows a strict three-layer architecture:
-    // 1. ControlContext (shared session state)
-    // 2. ControlDispatcher (protocol routing SDK ↔ CLI)
-    // 3. ControlService (programmatic API for CLI runtime)
-    //
-    // Application code MUST interact with the control plane exclusively through
-    // ControlService. ControlDispatcher is reserved for protocol-level message
-    // routing and should never be used directly outside of this file.
     this.controlContext = new ControlContext({
       config: this.config,
       streamJson: this.outputAdapter,
@@ -299,25 +127,32 @@ class SessionManager {
       | CLIControlResponse
       | ControlCancelRequest,
   ): Promise<boolean> {
-    const routed = this.route(message);
-
-    if (routed.type === 'control_request') {
-      const request = routed.message as CLIControlRequest;
+    if (isControlRequest(message)) {
+      const request = message as CLIControlRequest;
       this.controlSystemEnabled = true;
       this.ensureControlSystem();
       if (request.request.subtype === 'initialize') {
+        // Dispatch the initialize request first
         await this.dispatcher?.dispatch(request);
-        this.state = SESSION_STATE.IDLE;
+
+        // After handling initialize control request, initialize the config
+        // This is the SDK mode where config initialization is deferred
+        await this.ensureConfigInitialized();
         return true;
       }
-      return false;
+      if (this.debugMode) {
+        console.error(
+          '[Session] Ignoring non-initialize control request during initialization',
+        );
+      }
+      return true;
     }
 
-    if (routed.type === 'user') {
+    if (isCLIUserMessage(message)) {
       this.controlSystemEnabled = false;
-      this.state = SESSION_STATE.PROCESSING_QUERY;
-      this.userMessageQueue.push(routed.message as CLIUserMessage);
-      await this.processUserMessageQueue();
+      // For non-SDK mode (direct user message), initialize config if not already done
+      await this.ensureConfigInitialized();
+      this.enqueueUserMessage(message as CLIUserMessage);
       return true;
     }
 
@@ -325,241 +160,50 @@ class SessionManager {
     return false;
   }
 
-  /**
-   * Process a single message from the stream
-   */
-  private async processMessage(
-    message:
-      | CLIMessage
-      | CLIControlRequest
-      | CLIControlResponse
-      | ControlCancelRequest,
+  private async handleControlRequest(
+    request: CLIControlRequest,
   ): Promise<void> {
-    const routed = this.route(message);
-
-    if (this.debugMode) {
-      console.error(
-        `[SessionManager] State: ${this.state}, Message type: ${routed.type}`,
-      );
-    }
-
-    switch (this.state) {
-      case SESSION_STATE.INITIALIZING:
-        await this.handleInitializingState(routed);
-        break;
-
-      case SESSION_STATE.IDLE:
-        await this.handleIdleState(routed);
-        break;
-
-      case SESSION_STATE.PROCESSING_QUERY:
-        await this.handleProcessingState(routed);
-        break;
-
-      case SESSION_STATE.SHUTTING_DOWN:
-        // Ignore all messages during shutdown
-        break;
-
-      default: {
-        // Exhaustive check
-        const _exhaustiveCheck: never = this.state;
-        if (this.debugMode) {
-          console.error('[SessionManager] Unknown state:', _exhaustiveCheck);
-        }
-        break;
-      }
-    }
-  }
-
-  /**
-   * Handle messages in initializing state
-   */
-  private async handleInitializingState(routed: RoutedMessage): Promise<void> {
-    if (routed.type === 'control_request') {
-      const request = routed.message as CLIControlRequest;
-      const dispatcher = this.getDispatcher();
-      if (!dispatcher) {
-        if (this.debugMode) {
-          console.error(
-            '[SessionManager] Control request received before control system initialization',
-          );
-        }
-        return;
-      }
-      if (request.request.subtype === 'initialize') {
-        await dispatcher.dispatch(request);
-        this.state = SESSION_STATE.IDLE;
-        if (this.debugMode) {
-          console.error('[SessionManager] Initialized, transitioning to idle');
-        }
-      } else {
-        if (this.debugMode) {
-          console.error(
-            '[SessionManager] Ignoring non-initialize control request during initialization',
-          );
-        }
-      }
-    } else {
-      if (this.debugMode) {
-        console.error(
-          '[SessionManager] Ignoring non-control message during initialization',
-        );
-      }
-    }
-  }
-
-  /**
-   * Handle messages in idle state
-   */
-  private async handleIdleState(routed: RoutedMessage): Promise<void> {
     const dispatcher = this.getDispatcher();
-    if (routed.type === 'control_request') {
-      if (!dispatcher) {
-        if (this.debugMode) {
-          console.error('[SessionManager] Ignoring control request (disabled)');
-        }
-        return;
-      }
-      const request = routed.message as CLIControlRequest;
-      await dispatcher.dispatch(request);
-      // Stay in idle state
-    } else if (routed.type === 'control_response') {
-      if (!dispatcher) {
-        return;
-      }
-      const response = routed.message as CLIControlResponse;
-      dispatcher.handleControlResponse(response);
-      // Stay in idle state
-    } else if (routed.type === 'control_cancel') {
-      if (!dispatcher) {
-        return;
-      }
-      const cancelRequest = routed.message as ControlCancelRequest;
-      dispatcher.handleCancel(cancelRequest.request_id);
-    } else if (routed.type === 'user') {
-      const userMessage = routed.message as CLIUserMessage;
-      this.userMessageQueue.push(userMessage);
-      // Start processing queue
-      await this.processUserMessageQueue();
-    } else {
+    if (!dispatcher) {
       if (this.debugMode) {
-        console.error(
-          '[SessionManager] Ignoring message type in idle state:',
-          routed.type,
-        );
+        console.error('[Session] Control system not enabled');
       }
-    }
-  }
-
-  /**
-   * Handle messages in processing state
-   */
-  private async handleProcessingState(routed: RoutedMessage): Promise<void> {
-    const dispatcher = this.getDispatcher();
-    if (routed.type === 'control_request') {
-      if (!dispatcher) {
-        if (this.debugMode) {
-          console.error(
-            '[SessionManager] Control request ignored during processing (disabled)',
-          );
-        }
-        return;
-      }
-      const request = routed.message as CLIControlRequest;
-      await dispatcher.dispatch(request);
-      // Continue processing
-    } else if (routed.type === 'control_response') {
-      if (!dispatcher) {
-        return;
-      }
-      const response = routed.message as CLIControlResponse;
-      dispatcher.handleControlResponse(response);
-      // Continue processing
-    } else if (routed.type === 'user') {
-      // Enqueue for later
-      const userMessage = routed.message as CLIUserMessage;
-      this.userMessageQueue.push(userMessage);
-      if (this.debugMode) {
-        console.error(
-          '[SessionManager] Enqueued user message during processing',
-        );
-      }
-    } else {
-      if (this.debugMode) {
-        console.error(
-          '[SessionManager] Ignoring message type during processing:',
-          routed.type,
-        );
-      }
-    }
-  }
-
-  /**
-   * Process user message queue (FIFO)
-   */
-  private async processUserMessageQueue(): Promise<void> {
-    while (
-      this.userMessageQueue.length > 0 &&
-      !this.abortController.signal.aborted
-    ) {
-      this.state = SESSION_STATE.PROCESSING_QUERY;
-      const userMessage = this.userMessageQueue.shift()!;
-
-      try {
-        await this.processUserMessage(userMessage);
-      } catch (error) {
-        if (this.debugMode) {
-          console.error(
-            '[SessionManager] Error processing user message:',
-            error,
-          );
-        }
-        // Send error result
-        this.emitErrorResult(error);
-      }
-    }
-
-    // If control system is disabled (single-query mode) and queue is empty,
-    // automatically shutdown instead of returning to idle
-    if (
-      !this.abortController.signal.aborted &&
-      this.state === SESSION_STATE.PROCESSING_QUERY &&
-      this.controlSystemEnabled === false &&
-      this.userMessageQueue.length === 0
-    ) {
-      if (this.debugMode) {
-        console.error(
-          '[SessionManager] Single-query mode: queue processed, shutting down',
-        );
-      }
-      this.state = SESSION_STATE.SHUTTING_DOWN;
       return;
     }
 
-    // Return to idle after processing queue (for multi-query mode with control system)
-    if (
-      !this.abortController.signal.aborted &&
-      this.state === SESSION_STATE.PROCESSING_QUERY
-    ) {
-      this.state = SESSION_STATE.IDLE;
-      if (this.debugMode) {
-        console.error('[SessionManager] Queue processed, returning to idle');
-      }
-    }
+    await dispatcher.dispatch(request);
+  }
+
+  private handleControlResponse(response: CLIControlResponse): void {
+    const dispatcher = this.getDispatcher();
+    if (!dispatcher) {
+      return;
+    }
+
+    dispatcher.handleControlResponse(response);
+  }
+
+  private handleControlCancel(cancelRequest: ControlCancelRequest): void {
+    const dispatcher = this.getDispatcher();
+    if (!dispatcher) {
+      return;
+    }
+
+    dispatcher.handleCancel(cancelRequest.request_id);
   }
 
-  /**
-   * Process a single user message
-   */
   private async processUserMessage(userMessage: CLIUserMessage): Promise<void> {
     const input = extractUserMessageText(userMessage);
     if (!input) {
       if (this.debugMode) {
-        console.error('[SessionManager] No text content in user message');
+        console.error('[Session] No text content in user message');
       }
       return;
     }
 
+    // Ensure config is initialized before processing user messages
+    await this.ensureConfigInitialized();
+
     const promptId = this.getNextPromptId();
 
     try {
@@ -575,16 +219,56 @@ class SessionManager {
         },
       );
     } catch (error) {
-      // Error already handled by runNonInteractive via adapter.emitResult
       if (this.debugMode) {
-        console.error('[SessionManager] Query execution error:', error);
+        console.error('[Session] Query execution error:', error);
       }
     }
   }
 
-  /**
-   * Send tool results as user message
-   */
+  private async processUserMessageQueue(): Promise<void> {
+    if (this.isShuttingDown || this.abortController.signal.aborted) {
+      return;
+    }
+
+    while (
+      this.userMessageQueue.length > 0 &&
+      !this.isShuttingDown &&
+      !this.abortController.signal.aborted
+    ) {
+      const userMessage = this.userMessageQueue.shift()!;
+      try {
+        await this.processUserMessage(userMessage);
+      } catch (error) {
+        if (this.debugMode) {
+          console.error('[Session] Error processing user message:', error);
+        }
+        this.emitErrorResult(error);
+      }
+    }
+  }
+
+  private enqueueUserMessage(userMessage: CLIUserMessage): void {
+    this.userMessageQueue.push(userMessage);
+    this.ensureProcessingStarted();
+  }
+
+  private ensureProcessingStarted(): void {
+    if (this.processingPromise) {
+      return;
+    }
+
+    this.processingPromise = this.processUserMessageQueue().finally(() => {
+      this.processingPromise = null;
+      if (
+        this.userMessageQueue.length > 0 &&
+        !this.isShuttingDown &&
+        !this.abortController.signal.aborted
+      ) {
+        this.ensureProcessingStarted();
+      }
+    });
+  }
+
   private emitErrorResult(
     error: unknown,
     numTurns: number = 0,
@@ -602,52 +286,51 @@ class SessionManager {
     });
   }
 
-  /**
-   * Handle interrupt control request
-   */
   private handleInterrupt(): void {
     if (this.debugMode) {
-      console.error('[SessionManager] Interrupt requested');
-    }
-    // Abort current query if processing
-    if (this.state === SESSION_STATE.PROCESSING_QUERY) {
-      this.abortController.abort();
-      this.abortController = new AbortController(); // Create new controller for next query
+      console.error('[Session] Interrupt requested');
     }
+    this.abortController.abort();
+    this.abortController = new AbortController();
   }
 
-  /**
-   * Setup signal handlers for graceful shutdown
-   */
   private setupSignalHandlers(): void {
     this.shutdownHandler = () => {
       if (this.debugMode) {
-        console.error('[SessionManager] Shutdown signal received');
+        console.error('[Session] Shutdown signal received');
       }
+      this.isShuttingDown = true;
       this.abortController.abort();
-      this.state = SESSION_STATE.SHUTTING_DOWN;
     };
 
     process.on('SIGINT', this.shutdownHandler);
     process.on('SIGTERM', this.shutdownHandler);
   }
 
-  /**
-   * Shutdown session and cleanup resources
-   */
   private async shutdown(): Promise<void> {
     if (this.debugMode) {
-      console.error('[SessionManager] Shutting down');
+      console.error('[Session] Shutting down');
+    }
+
+    this.isShuttingDown = true;
+
+    if (this.processingPromise) {
+      try {
+        await this.processingPromise;
+      } catch (error) {
+        if (this.debugMode) {
+          console.error(
+            '[Session] Error waiting for processing to complete:',
+            error,
+          );
+        }
+      }
     }
 
-    this.state = SESSION_STATE.SHUTTING_DOWN;
     this.dispatcher?.shutdown();
     this.cleanupSignalHandlers();
   }
 
-  /**
-   * Remove signal handlers to prevent memory leaks
-   */
   private cleanupSignalHandlers(): void {
     if (this.shutdownHandler) {
       process.removeListener('SIGINT', this.shutdownHandler);
@@ -655,6 +338,94 @@ class SessionManager {
       this.shutdownHandler = null;
     }
   }
+
+  async run(): Promise<void> {
+    try {
+      if (this.debugMode) {
+        console.error('[Session] Starting session', this.sessionId);
+      }
+
+      if (this.initialPrompt !== null) {
+        const handled = await this.handleFirstMessage(this.initialPrompt);
+        if (handled && this.isShuttingDown) {
+          await this.shutdown();
+          return;
+        }
+      }
+
+      try {
+        for await (const message of this.inputReader.read()) {
+          if (this.abortController.signal.aborted) {
+            break;
+          }
+
+          if (this.controlSystemEnabled === null) {
+            const handled = await this.handleFirstMessage(message);
+            if (handled) {
+              if (this.isShuttingDown) {
+                break;
+              }
+              continue;
+            }
+          }
+
+          if (isControlRequest(message)) {
+            await this.handleControlRequest(message as CLIControlRequest);
+          } else if (isControlResponse(message)) {
+            this.handleControlResponse(message as CLIControlResponse);
+          } else if (isControlCancel(message)) {
+            this.handleControlCancel(message as ControlCancelRequest);
+          } else if (isCLIUserMessage(message)) {
+            this.enqueueUserMessage(message as CLIUserMessage);
+          } else if (this.debugMode) {
+            if (
+              !isCLIAssistantMessage(message) &&
+              !isCLISystemMessage(message) &&
+              !isCLIResultMessage(message) &&
+              !isCLIPartialAssistantMessage(message)
+            ) {
+              console.error(
+                '[Session] Unknown message type:',
+                JSON.stringify(message, null, 2),
+              );
+            }
+          }
+
+          if (this.isShuttingDown) {
+            break;
+          }
+        }
+      } catch (streamError) {
+        if (this.debugMode) {
+          console.error('[Session] Stream reading error:', streamError);
+        }
+        throw streamError;
+      }
+
+      while (this.processingPromise) {
+        if (this.debugMode) {
+          console.error('[Session] Waiting for final processing to complete');
+        }
+        try {
+          await this.processingPromise;
+        } catch (error) {
+          if (this.debugMode) {
+            console.error('[Session] Error in final processing:', error);
+          }
+        }
+      }
+
+      await this.shutdown();
+    } catch (error) {
+      if (this.debugMode) {
+        console.error('[Session] Error:', error);
+      }
+      await this.shutdown();
+      throw error;
+    } finally {
+      this.cleanupSignalHandlers();
+    }
+  }
 }
 
 function extractUserMessageText(message: CLIUserMessage): string | null {
@@ -682,12 +453,6 @@ function extractUserMessageText(message: CLIUserMessage): string | null {
   return null;
 }
 
-/**
- * Entry point for stream-json mode
- *
- * @param config - Configuration object
- * @param input - Optional initial prompt input to process before reading from stream
- */
 export async function runNonInteractiveStreamJson(
   config: Config,
   input: string,
@@ -698,7 +463,6 @@ export async function runNonInteractiveStreamJson(
   consolePatcher.patch();
 
   try {
-    // Create initial user message from prompt input if provided
     let initialPrompt: CLIUserMessage | undefined = undefined;
     if (input && input.trim().length > 0) {
       const sessionId = config.getSessionId();
@@ -713,7 +477,7 @@ export async function runNonInteractiveStreamJson(
       };
     }
 
-    const manager = new SessionManager(config, initialPrompt);
+    const manager = new Session(config, initialPrompt);
     await manager.run();
   } finally {
     consolePatcher.cleanup();

packages/cli/src/nonInteractive/types.ts

@@ -1,4 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import type {
+  MCPServerConfig,
+  SubagentConfig,
+} from '@qwen-code/qwen-code-core';
 
 /**
  * Annotation for attaching metadata to content blocks
@@ -137,9 +141,8 @@ export interface CLISystemMessage {
     status: string;
   }>;
   model?: string;
-  permissionMode?: string;
+  permission_mode?: string;
   slash_commands?: string[];
-  apiKeySource?: string;
   qwen_code_version?: string;
   output_style?: string;
   agents?: string[];
@@ -298,7 +301,9 @@ export interface CLIControlPermissionRequest {
 export interface CLIControlInitializeRequest {
   subtype: 'initialize';
   hooks?: HookRegistration[] | null;
-  sdkMcpServers?: string[];
+  sdkMcpServers?: Record<string, MCPServerConfig>;
+  mcpServers?: Record<string, MCPServerConfig>;
+  agents?: SubagentConfig[];
 }
 
 export interface CLIControlSetPermissionModeRequest {

packages/cli/src/nonInteractiveCli.test.ts

@@ -245,6 +245,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Test input' }],
       expect.any(AbortSignal),
       'prompt-id-1',
+      { isContinuation: false },
     );
     expect(processStdoutSpy).toHaveBeenCalledWith('Hello');
     expect(processStdoutSpy).toHaveBeenCalledWith(' World');
@@ -293,11 +294,21 @@ describe('runNonInteractive', () => {
       expect.any(AbortSignal),
       undefined,
     );
+    // Verify first call has isContinuation: false
+    expect(mockGeminiClient.sendMessageStream).toHaveBeenNthCalledWith(
+      1,
+      [{ text: 'Use a tool' }],
+      expect.any(AbortSignal),
+      'prompt-id-2',
+      { isContinuation: false },
+    );
+    // Verify second call (after tool execution) has isContinuation: true
     expect(mockGeminiClient.sendMessageStream).toHaveBeenNthCalledWith(
       2,
       [{ text: 'Tool response' }],
       expect.any(AbortSignal),
       'prompt-id-2',
+      { isContinuation: true },
     );
     expect(processStdoutSpy).toHaveBeenCalledWith('Final answer');
     expect(processStdoutSpy).toHaveBeenCalledWith('\n');
@@ -372,6 +383,7 @@ describe('runNonInteractive', () => {
       ],
       expect.any(AbortSignal),
       'prompt-id-3',
+      { isContinuation: true },
     );
     expect(processStdoutSpy).toHaveBeenCalledWith('Sorry, let me try again.');
   });
@@ -497,6 +509,7 @@ describe('runNonInteractive', () => {
       processedParts,
       expect.any(AbortSignal),
       'prompt-id-7',
+      { isContinuation: false },
     );
 
     // 6. Assert the final output is correct
@@ -528,6 +541,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Test input' }],
       expect.any(AbortSignal),
       'prompt-id-1',
+      { isContinuation: false },
     );
 
     // JSON adapter emits array of messages, last one is result with stats
@@ -680,6 +694,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Empty response test' }],
       expect.any(AbortSignal),
       'prompt-id-empty',
+      { isContinuation: false },
     );
 
     // JSON adapter emits array of messages, last one is result with stats
@@ -831,6 +846,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Prompt from command' }],
       expect.any(AbortSignal),
       'prompt-id-slash',
+      { isContinuation: false },
     );
 
     expect(processStdoutSpy).toHaveBeenCalledWith('Response from command');
@@ -887,6 +903,7 @@ describe('runNonInteractive', () => {
       [{ text: '/unknowncommand' }],
       expect.any(AbortSignal),
       'prompt-id-unknown',
+      { isContinuation: false },
     );
 
     expect(processStdoutSpy).toHaveBeenCalledWith('Response to unknown');
@@ -1217,6 +1234,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Message from stream-json input' }],
       expect.any(AbortSignal),
       'prompt-envelope',
+      { isContinuation: false },
     );
   });
 
@@ -1692,6 +1710,7 @@ describe('runNonInteractive', () => {
       [{ text: 'Simple string content' }],
       expect.any(AbortSignal),
       'prompt-string-content',
+      { isContinuation: false },
     );
 
     // UserMessage with array of text blocks
@@ -1724,6 +1743,7 @@ describe('runNonInteractive', () => {
       [{ text: 'First part' }, { text: 'Second part' }],
       expect.any(AbortSignal),
       'prompt-blocks-content',
+      { isContinuation: false },
     );
   });
 });

packages/cli/src/nonInteractiveCli.ts

@@ -15,7 +15,9 @@ import {
   FatalInputError,
   promptIdContext,
   OutputFormat,
+  InputFormat,
   uiTelemetryService,
+  parseAndFormatApiError,
 } from '@qwen-code/qwen-code-core';
 import type { Content, Part, PartListUnion } from '@google/genai';
 import type { CLIUserMessage, PermissionMode } from './nonInteractive/types.js';
@@ -170,6 +172,7 @@ export async function runNonInteractive(
         adapter.emitMessage(systemMessage);
       }
 
+      let isFirstTurn = true;
       while (true) {
         turnCount++;
         if (
@@ -185,7 +188,9 @@ export async function runNonInteractive(
           currentMessages[0]?.parts || [],
           abortController.signal,
           prompt_id,
+          { isContinuation: !isFirstTurn },
         );
+        isFirstTurn = false;
 
         // Start assistant message for this turn
         if (adapter) {
@@ -205,10 +210,21 @@ export async function runNonInteractive(
             }
           } else {
             // Text output mode - direct stdout
-            if (event.type === GeminiEventType.Content) {
+            if (event.type === GeminiEventType.Thought) {
+              process.stdout.write(event.value.description);
+            } else if (event.type === GeminiEventType.Content) {
               process.stdout.write(event.value);
             } else if (event.type === GeminiEventType.ToolCallRequest) {
               toolCallRequests.push(event.value);
+            } else if (event.type === GeminiEventType.Error) {
+              // Format and output the error message for text mode
+              const errorText = parseAndFormatApiError(
+                event.value.error,
+                config.getContentGeneratorConfig()?.authType,
+                undefined,
+                config.getModel(),
+              );
+              process.stderr.write(`${errorText}\n`);
             }
           }
         }
@@ -225,40 +241,14 @@ export async function runNonInteractive(
           for (const requestInfo of toolCallRequests) {
             const finalRequestInfo = requestInfo;
 
-            /*
-            if (options.controlService) {
-              const permissionResult =
-                await options.controlService.permission.shouldAllowTool(
-                  requestInfo,
-                );
-              if (!permissionResult.allowed) {
-                if (config.getDebugMode()) {
-                  console.error(
-                    `[runNonInteractive] Tool execution denied: ${requestInfo.name}`,
-                    permissionResult.message ?? '',
-                  );
-                }
-                if (adapter && permissionResult.message) {
-                  adapter.emitSystemMessage('tool_denied', {
-                    tool: requestInfo.name,
-                    message: permissionResult.message,
-                  });
-                }
-                continue;
-              }
-
-              if (permissionResult.updatedArgs) {
-                finalRequestInfo = {
-                  ...requestInfo,
-                  args: permissionResult.updatedArgs,
-                };
-              }
-            }
-
-            const toolCallUpdateCallback = options.controlService
-              ? options.controlService.permission.getToolCallUpdateCallback()
-              : undefined;
-            */
+            const inputFormat =
+              typeof config.getInputFormat === 'function'
+                ? config.getInputFormat()
+                : InputFormat.TEXT;
+            const toolCallUpdateCallback =
+              inputFormat === InputFormat.STREAM_JSON && options.controlService
+                ? options.controlService.permission.getToolCallUpdateCallback()
+                : undefined;
 
             // Only pass outputUpdateHandler for Task tool
             const isTaskTool = finalRequestInfo.name === 'task';
@@ -277,13 +267,13 @@ export async function runNonInteractive(
               isTaskTool && taskToolProgressHandler
                 ? {
                     outputUpdateHandler: taskToolProgressHandler,
-                    /*
-                    toolCallUpdateCallback
-                      ? { onToolCallsUpdate: toolCallUpdateCallback }
-                      : undefined,
-                    */
+                    onToolCallsUpdate: toolCallUpdateCallback,
                   }
-                : undefined,
+                : toolCallUpdateCallback
+                  ? {
+                      onToolCallsUpdate: toolCallUpdateCallback,
+                    }
+                  : undefined,
             );
 
             // Note: In JSON mode, subagent messages are automatically added to the main
@@ -303,9 +293,6 @@ export async function runNonInteractive(
                   ? toolResponse.resultDisplay
                   : undefined,
               );
-              // Note: We no longer emit a separate system message for tool errors
-              // in JSON/STREAM_JSON mode, as the error is already captured in the
-              // tool_result block with is_error=true.
             }
 
             if (adapter) {

packages/cli/src/services/BuiltinCommandLoader.test.ts

@@ -71,7 +71,6 @@ vi.mock('../ui/commands/modelCommand.js', () => ({
 }));
 vi.mock('../ui/commands/quitCommand.js', () => ({
   quitCommand: {},
-  quitConfirmCommand: {},
 }));
 vi.mock('../ui/commands/statsCommand.js', () => ({ statsCommand: {} }));
 vi.mock('../ui/commands/themeCommand.js', () => ({ themeCommand: {} }));

packages/cli/src/services/BuiltinCommandLoader.ts

@@ -28,7 +28,7 @@ import { mcpCommand } from '../ui/commands/mcpCommand.js';
 import { memoryCommand } from '../ui/commands/memoryCommand.js';
 import { modelCommand } from '../ui/commands/modelCommand.js';
 import { permissionsCommand } from '../ui/commands/permissionsCommand.js';
-import { quitCommand, quitConfirmCommand } from '../ui/commands/quitCommand.js';
+import { quitCommand } from '../ui/commands/quitCommand.js';
 import { restoreCommand } from '../ui/commands/restoreCommand.js';
 import { settingsCommand } from '../ui/commands/settingsCommand.js';
 import { statsCommand } from '../ui/commands/statsCommand.js';
@@ -77,7 +77,6 @@ export class BuiltinCommandLoader implements ICommandLoader {
       modelCommand,
       ...(this.config?.getFolderTrust() ? [permissionsCommand] : []),
       quitCommand,
-      quitConfirmCommand,
       restoreCommand(this.config),
       statsCommand,
       summaryCommand,

packages/cli/src/ui/AppContainer.tsx

@@ -89,7 +89,6 @@ import { useSessionStats } from './contexts/SessionContext.js';
 import { useGitBranchName } from './hooks/useGitBranchName.js';
 import { useExtensionUpdates } from './hooks/useExtensionUpdates.js';
 import { ShellFocusContext } from './contexts/ShellFocusContext.js';
-import { useQuitConfirmation } from './hooks/useQuitConfirmation.js';
 import { t } from '../i18n/index.js';
 import { useWelcomeBack } from './hooks/useWelcomeBack.js';
 import { useDialogClose } from './hooks/useDialogClose.js';
@@ -446,8 +445,6 @@ export const AppContainer = (props: AppContainerProps) => {
 
   const { toggleVimEnabled } = useVimMode();
 
-  const { showQuitConfirmation } = useQuitConfirmation();
-
   const {
     isSubagentCreateDialogOpen,
     openSubagentCreateDialog,
@@ -493,7 +490,6 @@ export const AppContainer = (props: AppContainerProps) => {
       addConfirmUpdateExtensionRequest,
       openSubagentCreateDialog,
       openAgentsManagerDialog,
-      _showQuitConfirmation: showQuitConfirmation,
     }),
     [
       openAuthDialog,
@@ -507,7 +503,6 @@ export const AppContainer = (props: AppContainerProps) => {
       openPermissionsDialog,
       openApprovalModeDialog,
       addConfirmUpdateExtensionRequest,
-      showQuitConfirmation,
       openSubagentCreateDialog,
       openAgentsManagerDialog,
     ],
@@ -520,7 +515,6 @@ export const AppContainer = (props: AppContainerProps) => {
     commandContext,
     shellConfirmationRequest,
     confirmationRequest,
-    quitConfirmationRequest,
   } = useSlashCommandProcessor(
     config,
     settings,
@@ -969,7 +963,6 @@ export const AppContainer = (props: AppContainerProps) => {
     isFolderTrustDialogOpen,
     showWelcomeBackDialog,
     handleWelcomeBackClose,
-    quitConfirmationRequest,
   });
 
   const handleExit = useCallback(
@@ -983,25 +976,18 @@ export const AppContainer = (props: AppContainerProps) => {
         if (timerRef.current) {
           clearTimeout(timerRef.current);
         }
-        // Exit directly without showing confirmation dialog
+        // Exit directly
         handleSlashCommand('/quit');
         return;
       }
 
       // First press: Prioritize cleanup tasks
 
-      // Special case: If quit-confirm dialog is open, Ctrl+C means "quit immediately"
-      if (quitConfirmationRequest) {
-        handleSlashCommand('/quit');
-        return;
-      }
-
       // 1. Close other dialogs (highest priority)
       /**
        * For AuthDialog it is required to complete the authentication process,
        * otherwise user cannot proceed to the next step.
-       * So a quit on AuthDialog should go with normal two press quit
-       * and without quit-confirm dialog.
+       * So a quit on AuthDialog should go with normal two press quit.
        */
       if (isAuthDialogOpen) {
         setPressedOnce(true);
@@ -1022,14 +1008,17 @@ export const AppContainer = (props: AppContainerProps) => {
         return; // Request cancelled, end processing
       }
 
-      // 3. Clear input buffer (if has content)
+      // 4. Clear input buffer (if has content)
       if (buffer.text.length > 0) {
         buffer.setText('');
         return; // Input cleared, end processing
       }
 
-      // All cleanup tasks completed, show quit confirmation dialog
-      handleSlashCommand('/quit-confirm');
+      // All cleanup tasks completed, set flag for double-press to quit
+      setPressedOnce(true);
+      timerRef.current = setTimeout(() => {
+        setPressedOnce(false);
+      }, CTRL_EXIT_PROMPT_DURATION_MS);
     },
     [
       isAuthDialogOpen,
@@ -1037,7 +1026,6 @@ export const AppContainer = (props: AppContainerProps) => {
       closeAnyOpenDialog,
       streamingState,
       cancelOngoingRequest,
-      quitConfirmationRequest,
       buffer,
     ],
   );
@@ -1054,8 +1042,8 @@ export const AppContainer = (props: AppContainerProps) => {
           return;
         }
 
-        // On first press: set flag, start timer, and call handleExit for cleanup/quit-confirm
-        // On second press (within 500ms): handleExit sees flag and does fast quit
+        // On first press: set flag, start timer, and call handleExit for cleanup
+        // On second press (within timeout): handleExit sees flag and does fast quit
         if (!ctrlCPressedOnce) {
           setCtrlCPressedOnce(true);
           ctrlCTimerRef.current = setTimeout(() => {
@@ -1196,7 +1184,6 @@ export const AppContainer = (props: AppContainerProps) => {
     !!confirmationRequest ||
     confirmUpdateExtensionRequests.length > 0 ||
     !!loopDetectionConfirmationRequest ||
-    !!quitConfirmationRequest ||
     isThemeDialogOpen ||
     isSettingsDialogOpen ||
     isModelDialogOpen ||
@@ -1245,7 +1232,6 @@ export const AppContainer = (props: AppContainerProps) => {
       confirmationRequest,
       confirmUpdateExtensionRequests,
       loopDetectionConfirmationRequest,
-      quitConfirmationRequest,
       geminiMdFileCount,
       streamingState,
       initError,
@@ -1337,7 +1323,6 @@ export const AppContainer = (props: AppContainerProps) => {
       confirmationRequest,
       confirmUpdateExtensionRequests,
       loopDetectionConfirmationRequest,
-      quitConfirmationRequest,
       geminiMdFileCount,
       streamingState,
       initError,

packages/cli/src/ui/commands/quitCommand.ts

@@ -8,35 +8,6 @@ import { formatDuration } from '../utils/formatters.js';
 import { CommandKind, type SlashCommand } from './types.js';
 import { t } from '../../i18n/index.js';
 
-export const quitConfirmCommand: SlashCommand = {
-  name: 'quit-confirm',
-  get description() {
-    return t('Show quit confirmation dialog');
-  },
-  kind: CommandKind.BUILT_IN,
-  action: (context) => {
-    const now = Date.now();
-    const { sessionStartTime } = context.session.stats;
-    const wallDuration = now - sessionStartTime.getTime();
-
-    return {
-      type: 'quit_confirmation',
-      messages: [
-        {
-          type: 'user',
-          text: `/quit-confirm`,
-          id: now - 1,
-        },
-        {
-          type: 'quit_confirmation',
-          duration: formatDuration(wallDuration),
-          id: now,
-        },
-      ],
-    };
-  },
-};
-
 export const quitCommand: SlashCommand = {
   name: 'quit',
   altNames: ['exit'],

packages/cli/src/ui/commands/setupGithubCommand.test.ts

@@ -84,7 +84,7 @@ describe('setupGithubCommand', async () => {
 
     const expectedSubstrings = [
       `set -eEuo pipefail`,
-      `fakeOpenCommand "https://github.com/google-github-actions/run-gemini-cli`,
+      `fakeOpenCommand "https://github.com/QwenLM/qwen-code-action`,
     ];
 
     for (const substring of expectedSubstrings) {
@@ -112,7 +112,7 @@ describe('setupGithubCommand', async () => {
 
     if (gitignoreExists) {
       const gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
-      expect(gitignoreContent).toContain('.gemini/');
+      expect(gitignoreContent).toContain('.qwen/');
       expect(gitignoreContent).toContain('gha-creds-*.json');
     }
   });
@@ -135,7 +135,7 @@ describe('updateGitignore', () => {
     const gitignorePath = path.join(scratchDir, '.gitignore');
     const content = await fs.readFile(gitignorePath, 'utf8');
 
-    expect(content).toBe('.gemini/\ngha-creds-*.json\n');
+    expect(content).toBe('.qwen/\ngha-creds-*.json\n');
   });
 
   it('appends entries to existing .gitignore file', async () => {
@@ -148,13 +148,13 @@ describe('updateGitignore', () => {
     const content = await fs.readFile(gitignorePath, 'utf8');
 
     expect(content).toBe(
-      '# Existing content\nnode_modules/\n\n.gemini/\ngha-creds-*.json\n',
+      '# Existing content\nnode_modules/\n\n.qwen/\ngha-creds-*.json\n',
     );
   });
 
   it('does not add duplicate entries', async () => {
     const gitignorePath = path.join(scratchDir, '.gitignore');
-    const existingContent = '.gemini/\nsome-other-file\ngha-creds-*.json\n';
+    const existingContent = '.qwen/\nsome-other-file\ngha-creds-*.json\n';
     await fs.writeFile(gitignorePath, existingContent);
 
     await updateGitignore(scratchDir);
@@ -166,7 +166,7 @@ describe('updateGitignore', () => {
 
   it('adds only missing entries when some already exist', async () => {
     const gitignorePath = path.join(scratchDir, '.gitignore');
-    const existingContent = '.gemini/\nsome-other-file\n';
+    const existingContent = '.qwen/\nsome-other-file\n';
     await fs.writeFile(gitignorePath, existingContent);
 
     await updateGitignore(scratchDir);
@@ -174,17 +174,17 @@ describe('updateGitignore', () => {
     const content = await fs.readFile(gitignorePath, 'utf8');
 
     // Should add only the missing gha-creds-*.json entry
-    expect(content).toBe('.gemini/\nsome-other-file\n\ngha-creds-*.json\n');
+    expect(content).toBe('.qwen/\nsome-other-file\n\ngha-creds-*.json\n');
     expect(content).toContain('gha-creds-*.json');
-    // Should not duplicate .gemini/ entry
-    expect((content.match(/\.gemini\//g) || []).length).toBe(1);
+    // Should not duplicate .qwen/ entry
+    expect((content.match(/\.qwen\//g) || []).length).toBe(1);
   });
 
   it('does not get confused by entries in comments or as substrings', async () => {
     const gitignorePath = path.join(scratchDir, '.gitignore');
     const existingContent = [
-      '# This is a comment mentioning .gemini/ folder',
-      'my-app.gemini/config',
+      '# This is a comment mentioning .qwen/ folder',
+      'my-app.qwen/config',
       '# Another comment with gha-creds-*.json pattern',
       'some-other-gha-creds-file.json',
       '',
@@ -196,7 +196,7 @@ describe('updateGitignore', () => {
     const content = await fs.readFile(gitignorePath, 'utf8');
 
     // Should add both entries since they don't actually exist as gitignore rules
-    expect(content).toContain('.gemini/');
+    expect(content).toContain('.qwen/');
     expect(content).toContain('gha-creds-*.json');
 
     // Verify the entries were added (not just mentioned in comments)
@@ -204,9 +204,9 @@ describe('updateGitignore', () => {
       .split('\n')
       .map((line) => line.split('#')[0].trim())
       .filter((line) => line);
-    expect(lines).toContain('.gemini/');
+    expect(lines).toContain('.qwen/');
     expect(lines).toContain('gha-creds-*.json');
-    expect(lines).toContain('my-app.gemini/config');
+    expect(lines).toContain('my-app.qwen/config');
     expect(lines).toContain('some-other-gha-creds-file.json');
   });
 

packages/cli/src/ui/commands/setupGithubCommand.ts

@@ -23,11 +23,11 @@ import { getUrlOpenCommand } from '../../ui/utils/commandUtils.js';
 import { t } from '../../i18n/index.js';
 
 export const GITHUB_WORKFLOW_PATHS = [
-  'gemini-dispatch/gemini-dispatch.yml',
-  'gemini-assistant/gemini-invoke.yml',
-  'issue-triage/gemini-triage.yml',
-  'issue-triage/gemini-scheduled-triage.yml',
-  'pr-review/gemini-review.yml',
+  'qwen-dispatch/qwen-dispatch.yml',
+  'qwen-assistant/qwen-invoke.yml',
+  'issue-triage/qwen-triage.yml',
+  'issue-triage/qwen-scheduled-triage.yml',
+  'pr-review/qwen-review.yml',
 ];
 
 // Generate OS-specific commands to open the GitHub pages needed for setup.
@@ -50,9 +50,9 @@ function getOpenUrlsCommands(readmeUrl: string): string[] {
   return commands;
 }
 
-// Add Gemini CLI specific entries to .gitignore file
+// Add Qwen Code specific entries to .gitignore file
 export async function updateGitignore(gitRepoRoot: string): Promise<void> {
-  const gitignoreEntries = ['.gemini/', 'gha-creds-*.json'];
+  const gitignoreEntries = ['.qwen/', 'gha-creds-*.json'];
 
   const gitignorePath = path.join(gitRepoRoot, '.gitignore');
   try {
@@ -121,7 +121,7 @@ export const setupGithubCommand: SlashCommand = {
     // Get the latest release tag from GitHub
     const proxy = context?.services?.config?.getProxy();
     const releaseTag = await getLatestGitHubRelease(proxy);
-    const readmeUrl = `https://github.com/google-github-actions/run-gemini-cli/blob/${releaseTag}/README.md#quick-start`;
+    const readmeUrl = `https://github.com/QwenLM/qwen-code-action/blob/${releaseTag}/README.md#quick-start`;
 
     // Create the .github/workflows directory to download the files into
     const githubWorkflowsDir = path.join(gitRepoRoot, '.github', 'workflows');
@@ -143,7 +143,7 @@ export const setupGithubCommand: SlashCommand = {
     for (const workflow of GITHUB_WORKFLOW_PATHS) {
       downloads.push(
         (async () => {
-          const endpoint = `https://raw.githubusercontent.com/google-github-actions/run-gemini-cli/refs/tags/${releaseTag}/examples/workflows/${workflow}`;
+          const endpoint = `https://raw.githubusercontent.com/QwenLM/qwen-code-action/refs/tags/${releaseTag}/examples/workflows/${workflow}`;
           const response = await fetch(endpoint, {
             method: 'GET',
             dispatcher: proxy ? new ProxyAgent(proxy) : undefined,
@@ -204,8 +204,9 @@ export const setupGithubCommand: SlashCommand = {
       toolName: 'run_shell_command',
       toolArgs: {
         description:
-          'Setting up GitHub Actions to triage issues and review PRs with Gemini.',
+          'Setting up GitHub Actions to triage issues and review PRs with Qwen.',
         command,
+        is_background: false,
       },
     };
   },

packages/cli/src/ui/commands/types.ts

@@ -100,12 +100,6 @@ export interface QuitActionReturn {
   messages: HistoryItem[];
 }
 
-/** The return type for a command action that requests quit confirmation. */
-export interface QuitConfirmationActionReturn {
-  type: 'quit_confirmation';
-  messages: HistoryItem[];
-}
-
 /**
  * The return type for a command action that results in a simple message
  * being displayed to the user.
@@ -182,7 +176,6 @@ export type SlashCommandActionReturn =
   | ToolActionReturn
   | MessageActionReturn
   | QuitActionReturn
-  | QuitConfirmationActionReturn
   | OpenDialogActionReturn
   | LoadHistoryActionReturn
   | SubmitPromptActionReturn

packages/cli/src/ui/components/DialogManager.tsx

@@ -36,10 +36,6 @@ import { WelcomeBackDialog } from './WelcomeBackDialog.js';
 import { ModelSwitchDialog } from './ModelSwitchDialog.js';
 import { AgentCreationWizard } from './subagents/create/AgentCreationWizard.js';
 import { AgentsManagerDialog } from './subagents/manage/AgentsManagerDialog.js';
-import {
-  QuitConfirmationDialog,
-  QuitChoice,
-} from './QuitConfirmationDialog.js';
 
 interface DialogManagerProps {
   addItem: UseHistoryManagerReturn['addItem'];
@@ -127,24 +123,6 @@ export const DialogManager = ({
       />
     );
   }
-  if (uiState.quitConfirmationRequest) {
-    return (
-      <QuitConfirmationDialog
-        onSelect={(choice: QuitChoice) => {
-          if (choice === QuitChoice.CANCEL) {
-            uiState.quitConfirmationRequest?.onConfirm(false, 'cancel');
-          } else if (choice === QuitChoice.QUIT) {
-            uiState.quitConfirmationRequest?.onConfirm(true, 'quit');
-          } else if (choice === QuitChoice.SUMMARY_AND_QUIT) {
-            uiState.quitConfirmationRequest?.onConfirm(
-              true,
-              'summary_and_quit',
-            );
-          }
-        }}
-      />
-    );
-  }
   if (uiState.confirmationRequest) {
     return (
       <ConsentPrompt

packages/cli/src/ui/components/HistoryItemDisplay.tsx

@@ -15,6 +15,8 @@ import { InfoMessage } from './messages/InfoMessage.js';
 import { ErrorMessage } from './messages/ErrorMessage.js';
 import { ToolGroupMessage } from './messages/ToolGroupMessage.js';
 import { GeminiMessageContent } from './messages/GeminiMessageContent.js';
+import { GeminiThoughtMessage } from './messages/GeminiThoughtMessage.js';
+import { GeminiThoughtMessageContent } from './messages/GeminiThoughtMessageContent.js';
 import { CompressionMessage } from './messages/CompressionMessage.js';
 import { SummaryMessage } from './messages/SummaryMessage.js';
 import { WarningMessage } from './messages/WarningMessage.js';
@@ -85,6 +87,26 @@ const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
           terminalWidth={terminalWidth}
         />
       )}
+      {itemForDisplay.type === 'gemini_thought' && (
+        <GeminiThoughtMessage
+          text={itemForDisplay.text}
+          isPending={isPending}
+          availableTerminalHeight={
+            availableTerminalHeightGemini ?? availableTerminalHeight
+          }
+          terminalWidth={terminalWidth}
+        />
+      )}
+      {itemForDisplay.type === 'gemini_thought_content' && (
+        <GeminiThoughtMessageContent
+          text={itemForDisplay.text}
+          isPending={isPending}
+          availableTerminalHeight={
+            availableTerminalHeightGemini ?? availableTerminalHeight
+          }
+          terminalWidth={terminalWidth}
+        />
+      )}
       {itemForDisplay.type === 'info' && (
         <InfoMessage text={itemForDisplay.text} />
       )}
@@ -108,9 +130,6 @@ const HistoryItemDisplayComponent: React.FC<HistoryItemDisplayProps> = ({
       {itemForDisplay.type === 'quit' && (
         <SessionSummaryDisplay duration={itemForDisplay.duration} />
       )}
-      {itemForDisplay.type === 'quit_confirmation' && (
-        <SessionSummaryDisplay duration={itemForDisplay.duration} />
-      )}
       {itemForDisplay.type === 'tool_group' && (
         <ToolGroupMessage
           toolCalls={itemForDisplay.tools}

packages/cli/src/ui/components/QuitConfirmationDialog.tsx

@@ -1,73 +0,0 @@
-/**
- * @license
- * Copyright 2025 Qwen
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { Box, Text } from 'ink';
-import type React from 'react';
-import { Colors } from '../colors.js';
-import {
-  RadioButtonSelect,
-  type RadioSelectItem,
-} from './shared/RadioButtonSelect.js';
-import { useKeypress } from '../hooks/useKeypress.js';
-import { t } from '../../i18n/index.js';
-
-export enum QuitChoice {
-  CANCEL = 'cancel',
-  QUIT = 'quit',
-  SUMMARY_AND_QUIT = 'summary_and_quit',
-}
-
-interface QuitConfirmationDialogProps {
-  onSelect: (choice: QuitChoice) => void;
-}
-
-export const QuitConfirmationDialog: React.FC<QuitConfirmationDialogProps> = ({
-  onSelect,
-}) => {
-  useKeypress(
-    (key) => {
-      if (key.name === 'escape') {
-        onSelect(QuitChoice.CANCEL);
-      }
-    },
-    { isActive: true },
-  );
-
-  const options: Array<RadioSelectItem<QuitChoice>> = [
-    {
-      key: 'quit',
-      label: t('Quit immediately (/quit)'),
-      value: QuitChoice.QUIT,
-    },
-    {
-      key: 'summary-and-quit',
-      label: t('Generate summary and quit (/summary)'),
-      value: QuitChoice.SUMMARY_AND_QUIT,
-    },
-    {
-      key: 'cancel',
-      label: t('Cancel (stay in application)'),
-      value: QuitChoice.CANCEL,
-    },
-  ];
-
-  return (
-    <Box
-      flexDirection="column"
-      borderStyle="round"
-      borderColor={Colors.AccentYellow}
-      padding={1}
-      width="100%"
-      marginLeft={1}
-    >
-      <Box flexDirection="column" marginBottom={1}>
-        <Text>{t('What would you like to do before exiting?')}</Text>
-      </Box>
-
-      <RadioButtonSelect items={options} onSelect={onSelect} isFocused />
-    </Box>
-  );
-};

packages/cli/src/ui/components/messages/GeminiThoughtMessage.tsx

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Text, Box } from 'ink';
+import { MarkdownDisplay } from '../../utils/MarkdownDisplay.js';
+import { theme } from '../../semantic-colors.js';
+
+interface GeminiThoughtMessageProps {
+  text: string;
+  isPending: boolean;
+  availableTerminalHeight?: number;
+  terminalWidth: number;
+}
+
+/**
+ * Displays model thinking/reasoning text with a softer, dimmed style
+ * to visually distinguish it from regular content output.
+ */
+export const GeminiThoughtMessage: React.FC<GeminiThoughtMessageProps> = ({
+  text,
+  isPending,
+  availableTerminalHeight,
+  terminalWidth,
+}) => {
+  const prefix = '✦ ';
+  const prefixWidth = prefix.length;
+
+  return (
+    <Box flexDirection="row" marginBottom={1}>
+      <Box width={prefixWidth}>
+        <Text color={theme.text.secondary}>{prefix}</Text>
+      </Box>
+      <Box flexGrow={1} flexDirection="column">
+        <MarkdownDisplay
+          text={text}
+          isPending={isPending}
+          availableTerminalHeight={availableTerminalHeight}
+          terminalWidth={terminalWidth}
+          textColor={theme.text.secondary}
+        />
+      </Box>
+    </Box>
+  );
+};

packages/cli/src/ui/components/messages/GeminiThoughtMessageContent.tsx

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type React from 'react';
+import { Box } from 'ink';
+import { MarkdownDisplay } from '../../utils/MarkdownDisplay.js';
+import { theme } from '../../semantic-colors.js';
+
+interface GeminiThoughtMessageContentProps {
+  text: string;
+  isPending: boolean;
+  availableTerminalHeight?: number;
+  terminalWidth: number;
+}
+
+/**
+ * Continuation component for thought messages, similar to GeminiMessageContent.
+ * Used when a thought response gets too long and needs to be split for performance.
+ */
+export const GeminiThoughtMessageContent: React.FC<
+  GeminiThoughtMessageContentProps
+> = ({ text, isPending, availableTerminalHeight, terminalWidth }) => {
+  const originalPrefix = '✦ ';
+  const prefixWidth = originalPrefix.length;
+
+  return (
+    <Box flexDirection="column" paddingLeft={prefixWidth} marginBottom={1}>
+      <MarkdownDisplay
+        text={text}
+        isPending={isPending}
+        availableTerminalHeight={availableTerminalHeight}
+        terminalWidth={terminalWidth}
+        textColor={theme.text.secondary}
+      />
+    </Box>
+  );
+};

packages/cli/src/ui/components/subagents/manage/AgentEditStep.tsx

@@ -69,7 +69,10 @@ export function EditOptionsStep({
       if (selectedValue === 'editor') {
         // Launch editor directly
         try {
-          await launchEditor(selectedAgent?.filePath);
+          if (!selectedAgent.filePath) {
+            throw new Error('Agent has no file path');
+          }
+          await launchEditor(selectedAgent.filePath);
         } catch (err) {
           setError(
             t('Failed to launch editor: {{error}}', {

packages/cli/src/ui/components/subagents/manage/AgentSelectionStep.tsx

@@ -218,7 +218,7 @@ export const AgentSelectionStep = ({
   const renderAgentItem = (
     agent: {
       name: string;
-      level: 'project' | 'user' | 'builtin';
+      level: 'project' | 'user' | 'builtin' | 'session';
       isBuiltin?: boolean;
     },
     index: number,
@@ -267,7 +267,7 @@ export const AgentSelectionStep = ({
         <Box flexDirection="column" marginBottom={1}>
           <Text color={theme.text.primary} bold>
             {t('Project Level ({{path}})', {
-              path: projectAgents[0].filePath.replace(/\/[^/]+$/, ''),
+              path: projectAgents[0].filePath?.replace(/\/[^/]+$/, '') || '',
             })}
           </Text>
           <Box marginTop={1} flexDirection="column">
@@ -289,7 +289,7 @@ export const AgentSelectionStep = ({
         >
           <Text color={theme.text.primary} bold>
             {t('User Level ({{path}})', {
-              path: userAgents[0].filePath.replace(/\/[^/]+$/, ''),
+              path: userAgents[0].filePath?.replace(/\/[^/]+$/, '') || '',
             })}
           </Text>
           <Box marginTop={1} flexDirection="column">

packages/cli/src/ui/contexts/UIStateContext.tsx

@@ -12,7 +12,6 @@ import type {
   ShellConfirmationRequest,
   ConfirmationRequest,
   LoopDetectionConfirmationRequest,
-  QuitConfirmationRequest,
   HistoryItemWithoutId,
   StreamingState,
 } from '../types.js';
@@ -69,7 +68,6 @@ export interface UIState {
   confirmationRequest: ConfirmationRequest | null;
   confirmUpdateExtensionRequests: ConfirmationRequest[];
   loopDetectionConfirmationRequest: LoopDetectionConfirmationRequest | null;
-  quitConfirmationRequest: QuitConfirmationRequest | null;
   geminiMdFileCount: number;
   streamingState: StreamingState;
   initError: string | null;

packages/cli/src/ui/hooks/slashCommandProcessor.test.ts

@@ -918,7 +918,6 @@ describe('useSlashCommandProcessor', () => {
           vi.fn(), // toggleVimEnabled
           vi.fn(), // setIsProcessing
           vi.fn(), // setGeminiMdFileCount
-          vi.fn(), // _showQuitConfirmation
         ),
       );
 

packages/cli/src/ui/hooks/slashCommandProcessor.ts

@@ -18,7 +18,6 @@ import {
   IdeClient,
 } from '@qwen-code/qwen-code-core';
 import { useSessionStats } from '../contexts/SessionContext.js';
-import { formatDuration } from '../utils/formatters.js';
 import type {
   Message,
   HistoryItemWithoutId,
@@ -53,7 +52,6 @@ function serializeHistoryItemForRecording(
 
 const SLASH_COMMANDS_SKIP_RECORDING = new Set([
   'quit',
-  'quit-confirm',
   'exit',
   'clear',
   'reset',
@@ -75,7 +73,6 @@ interface SlashCommandProcessorActions {
   addConfirmUpdateExtensionRequest: (request: ConfirmationRequest) => void;
   openSubagentCreateDialog: () => void;
   openAgentsManagerDialog: () => void;
-  _showQuitConfirmation: () => void;
 }
 
 /**
@@ -115,10 +112,6 @@ export const useSlashCommandProcessor = (
     prompt: React.ReactNode;
     onConfirm: (confirmed: boolean) => void;
   }>(null);
-  const [quitConfirmationRequest, setQuitConfirmationRequest] =
-    useState<null | {
-      onConfirm: (shouldQuit: boolean, action?: string) => void;
-    }>(null);
 
   const [sessionShellAllowlist, setSessionShellAllowlist] = useState(
     new Set<string>(),
@@ -174,11 +167,6 @@ export const useSlashCommandProcessor = (
           type: 'quit',
           duration: message.duration,
         };
-      } else if (message.type === MessageType.QUIT_CONFIRMATION) {
-        historyItemContent = {
-          type: 'quit_confirmation',
-          duration: message.duration,
-        };
       } else if (message.type === MessageType.COMPRESSION) {
         historyItemContent = {
           type: 'compression',
@@ -449,66 +437,6 @@ export const useSlashCommandProcessor = (
                   });
                   return { type: 'handled' };
                 }
-                case 'quit_confirmation':
-                  // Show quit confirmation dialog instead of immediately quitting
-                  setQuitConfirmationRequest({
-                    onConfirm: (shouldQuit: boolean, action?: string) => {
-                      setQuitConfirmationRequest(null);
-                      if (!shouldQuit) {
-                        // User cancelled the quit operation - do nothing
-                        return;
-                      }
-                      if (shouldQuit) {
-                        if (action === 'summary_and_quit') {
-                          // Generate summary and then quit
-                          handleSlashCommand('/summary')
-                            .then(() => {
-                              // Wait for user to see the summary result
-                              setTimeout(() => {
-                                handleSlashCommand('/quit');
-                              }, 1200);
-                            })
-                            .catch((error) => {
-                              // If summary fails, still quit but show error
-                              addItemWithRecording(
-                                {
-                                  type: 'error',
-                                  text: `Failed to generate summary before quit: ${
-                                    error instanceof Error
-                                      ? error.message
-                                      : String(error)
-                                  }`,
-                                },
-                                Date.now(),
-                              );
-                              // Give user time to see the error message
-                              setTimeout(() => {
-                                handleSlashCommand('/quit');
-                              }, 1000);
-                            });
-                        } else {
-                          // Just quit immediately - trigger the actual quit action
-                          const now = Date.now();
-                          const { sessionStartTime } = sessionStats;
-                          const wallDuration = now - sessionStartTime.getTime();
-
-                          actions.quit([
-                            {
-                              type: 'user',
-                              text: `/quit`,
-                              id: now - 1,
-                            },
-                            {
-                              type: 'quit',
-                              duration: formatDuration(wallDuration),
-                              id: now,
-                            },
-                          ]);
-                        }
-                      }
-                    },
-                  });
-                  return { type: 'handled' };
 
                 case 'quit':
                   actions.quit(result.messages);
@@ -692,7 +620,6 @@ export const useSlashCommandProcessor = (
       setSessionShellAllowlist,
       setIsProcessing,
       setConfirmationRequest,
-      sessionStats,
     ],
   );
 
@@ -703,6 +630,5 @@ export const useSlashCommandProcessor = (
     commandContext,
     shellConfirmationRequest,
     confirmationRequest,
-    quitConfirmationRequest,
   };
 };

packages/cli/src/ui/hooks/useDialogClose.ts

@@ -44,11 +44,6 @@ export interface DialogCloseOptions {
   // Welcome back dialog
   showWelcomeBackDialog: boolean;
   handleWelcomeBackClose: () => void;
-
-  // Quit confirmation dialog
-  quitConfirmationRequest: {
-    onConfirm: (shouldQuit: boolean, action?: string) => void;
-  } | null;
 }
 
 /**
@@ -96,9 +91,6 @@ export function useDialogClose(options: DialogCloseOptions) {
       return true;
     }
 
-    // Note: quitConfirmationRequest is NOT handled here anymore
-    // It's handled specially in handleExit - ctrl+c in quit-confirm should exit immediately
-
     // No dialog was open
     return false;
   }, [options]);

packages/cli/src/ui/hooks/useGeminiStream.test.tsx

@@ -2261,6 +2261,57 @@ describe('useGeminiStream', () => {
       });
     });
 
+    it('should accumulate streamed thought descriptions', async () => {
+      mockSendMessageStream.mockReturnValue(
+        (async function* () {
+          yield {
+            type: ServerGeminiEventType.Thought,
+            value: { subject: '', description: 'thinking ' },
+          };
+          yield {
+            type: ServerGeminiEventType.Thought,
+            value: { subject: '', description: 'more' },
+          };
+          yield {
+            type: ServerGeminiEventType.Finished,
+            value: { reason: 'STOP', usageMetadata: undefined },
+          };
+        })(),
+      );
+
+      const { result } = renderHook(() =>
+        useGeminiStream(
+          new MockedGeminiClientClass(mockConfig),
+          [],
+          mockAddItem,
+          mockConfig,
+          mockLoadedSettings,
+          mockOnDebugMessage,
+          mockHandleSlashCommand,
+          false,
+          () => 'vscode' as EditorType,
+          () => {},
+          () => Promise.resolve(),
+          false,
+          () => {},
+          () => {},
+          () => {},
+          false, // visionModelPreviewEnabled
+          () => {},
+          80,
+          24,
+        ),
+      );
+
+      await act(async () => {
+        await result.current.submitQuery('Streamed thought');
+      });
+
+      await waitFor(() => {
+        expect(result.current.thought?.description).toBe('thinking more');
+      });
+    });
+
     it('should memoize pendingHistoryItems', () => {
       mockUseReactToolScheduler.mockReturnValue([
         [],

packages/cli/src/ui/hooks/useGeminiStream.ts

@@ -497,6 +497,61 @@ export const useGeminiStream = (
     [addItem, pendingHistoryItemRef, setPendingHistoryItem],
   );
 
+  const mergeThought = useCallback(
+    (incoming: ThoughtSummary) => {
+      setThought((prev) => {
+        if (!prev) {
+          return incoming;
+        }
+        const subject = incoming.subject || prev.subject;
+        const description = `${prev.description ?? ''}${incoming.description ?? ''}`;
+        return { subject, description };
+      });
+    },
+    [setThought],
+  );
+
+  const handleThoughtEvent = useCallback(
+    (
+      eventValue: ThoughtSummary,
+      currentThoughtBuffer: string,
+      userMessageTimestamp: number,
+    ): string => {
+      if (turnCancelledRef.current) {
+        return '';
+      }
+
+      // Extract the description text from the thought summary
+      const thoughtText = eventValue.description ?? '';
+      if (!thoughtText) {
+        return currentThoughtBuffer;
+      }
+
+      const newThoughtBuffer = currentThoughtBuffer + thoughtText;
+
+      // If we're not already showing a thought, start a new one
+      if (pendingHistoryItemRef.current?.type !== 'gemini_thought') {
+        // If there's a pending non-thought item, finalize it first
+        if (pendingHistoryItemRef.current) {
+          addItem(pendingHistoryItemRef.current, userMessageTimestamp);
+        }
+        setPendingHistoryItem({ type: 'gemini_thought', text: '' });
+      }
+
+      // Update the existing thought message with accumulated content
+      setPendingHistoryItem({
+        type: 'gemini_thought',
+        text: newThoughtBuffer,
+      });
+
+      // Also update the thought state for the loading indicator
+      mergeThought(eventValue);
+
+      return newThoughtBuffer;
+    },
+    [addItem, pendingHistoryItemRef, setPendingHistoryItem, mergeThought],
+  );
+
   const handleUserCancelledEvent = useCallback(
     (userMessageTimestamp: number) => {
       if (turnCancelledRef.current) {
@@ -710,11 +765,16 @@ export const useGeminiStream = (
       signal: AbortSignal,
     ): Promise<StreamProcessingStatus> => {
       let geminiMessageBuffer = '';
+      let thoughtBuffer = '';
       const toolCallRequests: ToolCallRequestInfo[] = [];
       for await (const event of stream) {
         switch (event.type) {
           case ServerGeminiEventType.Thought:
-            setThought(event.value);
+            thoughtBuffer = handleThoughtEvent(
+              event.value,
+              thoughtBuffer,
+              userMessageTimestamp,
+            );
             break;
           case ServerGeminiEventType.Content:
             geminiMessageBuffer = handleContentEvent(
@@ -776,6 +836,7 @@ export const useGeminiStream = (
     },
     [
       handleContentEvent,
+      handleThoughtEvent,
       handleUserCancelledEvent,
       handleErrorEvent,
       scheduleToolCalls,

packages/cli/src/ui/hooks/useQuitConfirmation.ts

@@ -1,37 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { useState, useCallback } from 'react';
-import { QuitChoice } from '../components/QuitConfirmationDialog.js';
-
-export const useQuitConfirmation = () => {
-  const [isQuitConfirmationOpen, setIsQuitConfirmationOpen] = useState(false);
-
-  const showQuitConfirmation = useCallback(() => {
-    setIsQuitConfirmationOpen(true);
-  }, []);
-
-  const handleQuitConfirmationSelect = useCallback((choice: QuitChoice) => {
-    setIsQuitConfirmationOpen(false);
-
-    if (choice === QuitChoice.CANCEL) {
-      return { shouldQuit: false, action: 'cancel' };
-    } else if (choice === QuitChoice.QUIT) {
-      return { shouldQuit: true, action: 'quit' };
-    } else if (choice === QuitChoice.SUMMARY_AND_QUIT) {
-      return { shouldQuit: true, action: 'summary_and_quit' };
-    }
-
-    // Default to cancel if unknown choice
-    return { shouldQuit: false, action: 'cancel' };
-  }, []);
-
-  return {
-    isQuitConfirmationOpen,
-    showQuitConfirmation,
-    handleQuitConfirmationSelect,
-  };
-};

packages/cli/src/ui/types.ts

@@ -103,6 +103,16 @@ export type HistoryItemGeminiContent = HistoryItemBase & {
   text: string;
 };
 
+export type HistoryItemGeminiThought = HistoryItemBase & {
+  type: 'gemini_thought';
+  text: string;
+};
+
+export type HistoryItemGeminiThoughtContent = HistoryItemBase & {
+  type: 'gemini_thought_content';
+  text: string;
+};
+
 export type HistoryItemInfo = HistoryItemBase & {
   type: 'info';
   text: string;
@@ -161,11 +171,6 @@ export type HistoryItemQuit = HistoryItemBase & {
   duration: string;
 };
 
-export type HistoryItemQuitConfirmation = HistoryItemBase & {
-  type: 'quit_confirmation';
-  duration: string;
-};
-
 export type HistoryItemToolGroup = HistoryItemBase & {
   type: 'tool_group';
   tools: IndividualToolCallDisplay[];
@@ -246,6 +251,8 @@ export type HistoryItemWithoutId =
   | HistoryItemUserShell
   | HistoryItemGemini
   | HistoryItemGeminiContent
+  | HistoryItemGeminiThought
+  | HistoryItemGeminiThoughtContent
   | HistoryItemInfo
   | HistoryItemError
   | HistoryItemWarning
@@ -256,7 +263,6 @@ export type HistoryItemWithoutId =
   | HistoryItemModelStats
   | HistoryItemToolStats
   | HistoryItemQuit
-  | HistoryItemQuitConfirmation
   | HistoryItemCompression
   | HistoryItemSummary
   | HistoryItemCompression
@@ -278,7 +284,6 @@ export enum MessageType {
   MODEL_STATS = 'model_stats',
   TOOL_STATS = 'tool_stats',
   QUIT = 'quit',
-  QUIT_CONFIRMATION = 'quit_confirmation',
   GEMINI = 'gemini',
   COMPRESSION = 'compression',
   SUMMARY = 'summary',
@@ -342,12 +347,6 @@ export type Message =
       duration: string;
       content?: string;
     }
-  | {
-      type: MessageType.QUIT_CONFIRMATION;
-      timestamp: Date;
-      duration: string;
-      content?: string;
-    }
   | {
       type: MessageType.COMPRESSION;
       compression: CompressionProps;
@@ -404,7 +403,3 @@ export interface ConfirmationRequest {
 export interface LoopDetectionConfirmationRequest {
   onComplete: (result: { userSelection: 'disable' | 'keep' }) => void;
 }
-
-export interface QuitConfirmationRequest {
-  onConfirm: (shouldQuit: boolean, action?: string) => void;
-}

packages/cli/src/ui/utils/InlineMarkdownRenderer.tsx

@@ -19,12 +19,16 @@ const UNDERLINE_TAG_END_LENGTH = 4; // For "</u>"
 
 interface RenderInlineProps {
   text: string;
+  textColor?: string;
 }
 
-const RenderInlineInternal: React.FC<RenderInlineProps> = ({ text }) => {
+const RenderInlineInternal: React.FC<RenderInlineProps> = ({
+  text,
+  textColor = theme.text.primary,
+}) => {
   // Early return for plain text without markdown or URLs
   if (!/[*_~`<[https?:]/.test(text)) {
-    return <Text color={theme.text.primary}>{text}</Text>;
+    return <Text color={textColor}>{text}</Text>;
   }
 
   const nodes: React.ReactNode[] = [];

packages/cli/src/ui/utils/MarkdownDisplay.tsx

@@ -17,6 +17,7 @@ interface MarkdownDisplayProps {
   isPending: boolean;
   availableTerminalHeight?: number;
   terminalWidth: number;
+  textColor?: string;
 }
 
 // Constants for Markdown parsing and rendering
@@ -31,6 +32,7 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
   isPending,
   availableTerminalHeight,
   terminalWidth,
+  textColor = theme.text.primary,
 }) => {
   if (!text) return <></>;
 
@@ -116,7 +118,7 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
         addContentBlock(
           <Box key={key}>
             <Text wrap="wrap">
-              <RenderInline text={line} />
+              <RenderInline text={line} textColor={textColor} />
             </Text>
           </Box>,
         );
@@ -155,7 +157,7 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
         addContentBlock(
           <Box key={key}>
             <Text wrap="wrap">
-              <RenderInline text={line} />
+              <RenderInline text={line} textColor={textColor} />
             </Text>
           </Box>,
         );
@@ -173,36 +175,36 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
       switch (level) {
         case 1:
           headerNode = (
-            <Text bold color={theme.text.link}>
-              <RenderInline text={headerText} />
+            <Text bold color={textColor}>
+              <RenderInline text={headerText} textColor={textColor} />
             </Text>
           );
           break;
         case 2:
           headerNode = (
-            <Text bold color={theme.text.link}>
-              <RenderInline text={headerText} />
+            <Text bold color={textColor}>
+              <RenderInline text={headerText} textColor={textColor} />
             </Text>
           );
           break;
         case 3:
           headerNode = (
-            <Text bold color={theme.text.primary}>
-              <RenderInline text={headerText} />
+            <Text bold color={textColor}>
+              <RenderInline text={headerText} textColor={textColor} />
             </Text>
           );
           break;
         case 4:
           headerNode = (
-            <Text italic color={theme.text.secondary}>
-              <RenderInline text={headerText} />
+            <Text italic color={textColor}>
+              <RenderInline text={headerText} textColor={textColor} />
             </Text>
           );
           break;
         default:
           headerNode = (
-            <Text color={theme.text.primary}>
-              <RenderInline text={headerText} />
+            <Text color={textColor}>
+              <RenderInline text={headerText} textColor={textColor} />
             </Text>
           );
           break;
@@ -219,6 +221,7 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
           type="ul"
           marker={marker}
           leadingWhitespace={leadingWhitespace}
+          textColor={textColor}
         />,
       );
     } else if (olMatch) {
@@ -232,6 +235,7 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
           type="ol"
           marker={marker}
           leadingWhitespace={leadingWhitespace}
+          textColor={textColor}
         />,
       );
     } else {
@@ -245,8 +249,8 @@ const MarkdownDisplayInternal: React.FC<MarkdownDisplayProps> = ({
       } else {
         addContentBlock(
           <Box key={key}>
-            <Text wrap="wrap" color={theme.text.primary}>
-              <RenderInline text={line} />
+            <Text wrap="wrap" color={textColor}>
+              <RenderInline text={line} textColor={textColor} />
             </Text>
           </Box>,
         );
@@ -367,6 +371,7 @@ interface RenderListItemProps {
   type: 'ul' | 'ol';
   marker: string;
   leadingWhitespace?: string;
+  textColor?: string;
 }
 
 const RenderListItemInternal: React.FC<RenderListItemProps> = ({
@@ -374,6 +379,7 @@ const RenderListItemInternal: React.FC<RenderListItemProps> = ({
   type,
   marker,
   leadingWhitespace = '',
+  textColor = theme.text.primary,
 }) => {
   const prefix = type === 'ol' ? `${marker}. ` : `${marker} `;
   const prefixWidth = prefix.length;
@@ -385,11 +391,11 @@ const RenderListItemInternal: React.FC<RenderListItemProps> = ({
       flexDirection="row"
     >
       <Box width={prefixWidth}>
-        <Text color={theme.text.primary}>{prefix}</Text>
+        <Text color={textColor}>{prefix}</Text>
       </Box>
       <Box flexGrow={LIST_ITEM_TEXT_FLEX_GROW}>
-        <Text wrap="wrap" color={theme.text.primary}>
-          <RenderInline text={itemText} />
+        <Text wrap="wrap" color={textColor}>
+          <RenderInline text={itemText} textColor={textColor} />
         </Text>
       </Box>
     </Box>

packages/cli/src/ui/utils/resumeHistoryUtils.test.ts

@@ -102,7 +102,7 @@ describe('resumeHistoryUtils', () => {
     ]);
   });
 
-  it('marks tool results as error, skips thought text, and falls back when tool is missing', () => {
+  it('marks tool results as error, captures thought text, and falls back when tool is missing', () => {
     const conversation = {
       messages: [
         {
@@ -142,6 +142,11 @@ describe('resumeHistoryUtils', () => {
     const items = buildResumedHistoryItems(session, makeConfig({}));
 
     expect(items).toEqual([
+      {
+        id: expect.any(Number),
+        type: 'gemini_thought',
+        text: 'should be skipped',
+      },
       { id: expect.any(Number), type: 'gemini', text: 'visible text' },
       {
         id: expect.any(Number),

packages/cli/src/ui/utils/resumeHistoryUtils.ts

@@ -17,7 +17,7 @@ import type { HistoryItem, HistoryItemWithoutId } from '../types.js';
 import { ToolCallStatus } from '../types.js';
 
 /**
- * Extracts text content from a Content object's parts.
+ * Extracts text content from a Content object's parts (excluding thought parts).
  */
 function extractTextFromParts(parts: Part[] | undefined): string {
   if (!parts) return '';
@@ -34,6 +34,22 @@ function extractTextFromParts(parts: Part[] | undefined): string {
   return textParts.join('\n');
 }
 
+/**
+ * Extracts thought text content from a Content object's parts.
+ * Thought parts are identified by having `thought: true`.
+ */
+function extractThoughtTextFromParts(parts: Part[] | undefined): string {
+  if (!parts) return '';
+
+  const thoughtParts: string[] = [];
+  for (const part of parts) {
+    if ('text' in part && part.text && 'thought' in part && part.thought) {
+      thoughtParts.push(part.text);
+    }
+  }
+  return thoughtParts.join('\n');
+}
+
 /**
  * Extracts function calls from a Content object's parts.
  */
@@ -187,12 +203,28 @@ function convertToHistoryItems(
       case 'assistant': {
         const parts = record.message?.parts as Part[] | undefined;
 
+        // Extract thought content
+        const thoughtText = extractThoughtTextFromParts(parts);
+
         // Extract text content (non-function-call, non-thought)
         const text = extractTextFromParts(parts);
 
         // Extract function calls
         const functionCalls = extractFunctionCalls(parts);
 
+        // If there's thought content, add it as a gemini_thought message
+        if (thoughtText) {
+          // Flush any pending tool group before thought
+          if (currentToolGroup.length > 0) {
+            items.push({
+              type: 'tool_group',
+              tools: [...currentToolGroup],
+            });
+            currentToolGroup = [];
+          }
+          items.push({ type: 'gemini_thought', text: thoughtText });
+        }
+
         // If there's text content, add it as a gemini message
         if (text) {
           // Flush any pending tool group before text

packages/cli/src/utils/gitUtils.ts

@@ -58,7 +58,7 @@ export const getLatestGitHubRelease = async (
   try {
     const controller = new AbortController();
 
-    const endpoint = `https://api.github.com/repos/google-github-actions/run-gemini-cli/releases/latest`;
+    const endpoint = `https://api.github.com/repos/QwenLM/qwen-code-action/releases/latest`;
 
     const response = await fetch(endpoint, {
       method: 'GET',
@@ -83,9 +83,12 @@ export const getLatestGitHubRelease = async (
     }
     return releaseTag;
   } catch (_error) {
-    console.debug(`Failed to determine latest run-gemini-cli release:`, _error);
+    console.debug(
+      `Failed to determine latest qwen-code-action release:`,
+      _error,
+    );
     throw new Error(
-      `Unable to determine the latest run-gemini-cli release on GitHub.`,
+      `Unable to determine the latest qwen-code-action release on GitHub.`,
     );
   }
 };

packages/cli/src/utils/nonInteractiveHelpers.test.ts

@@ -529,7 +529,7 @@ describe('buildSystemMessage', () => {
         { name: 'mcp-server-2', status: 'connected' },
       ],
       model: 'test-model',
-      permissionMode: 'auto',
+      permission_mode: 'auto',
       slash_commands: ['commit', 'help', 'memory'],
       qwen_code_version: '1.0.0',
       agents: [],

packages/cli/src/utils/nonInteractiveHelpers.ts

@@ -275,7 +275,7 @@ export async function buildSystemMessage(
     tools,
     mcp_servers: mcpServerList,
     model: config.getModel(),
-    permissionMode,
+    permission_mode: permissionMode,
     slash_commands: slashCommands,
     qwen_code_version: config.getCliVersion() || 'unknown',
     agents: agentNames,

packages/cli/src/validateNonInterActiveAuth.ts

@@ -41,7 +41,7 @@ export async function validateNonInteractiveAuth(
     }
 
     const effectiveAuthType =
-      enforcedType || getAuthTypeFromEnv() || configuredAuthType;
+      enforcedType || configuredAuthType || getAuthTypeFromEnv();
 
     if (!effectiveAuthType) {
       const message = `Please set an Auth method in your ${USER_SETTINGS_PATH} or specify one of the following environment variables before running: QWEN_OAUTH, OPENAI_API_KEY`;

packages/core/src/config/config.ts

@@ -65,6 +65,7 @@ import { ideContextStore } from '../ide/ideContext.js';
 import { InputFormat, OutputFormat } from '../output/types.js';
 import { PromptRegistry } from '../prompts/prompt-registry.js';
 import { SubagentManager } from '../subagents/subagent-manager.js';
+import type { SubagentConfig } from '../subagents/types.js';
 import {
   DEFAULT_OTLP_ENDPOINT,
   DEFAULT_TELEMETRY_TARGET,
@@ -333,9 +334,11 @@ export interface ConfigParameters {
   eventEmitter?: EventEmitter;
   useSmartEdit?: boolean;
   output?: OutputSettings;
-  skipStartupContext?: boolean;
   inputFormat?: InputFormat;
   outputFormat?: OutputFormat;
+  skipStartupContext?: boolean;
+  sdkMode?: boolean;
+  sessionSubagents?: SubagentConfig[];
 }
 
 function normalizeConfigOutputFormat(
@@ -383,8 +386,10 @@ export class Config {
   private readonly toolDiscoveryCommand: string | undefined;
   private readonly toolCallCommand: string | undefined;
   private readonly mcpServerCommand: string | undefined;
-  private readonly mcpServers: Record<string, MCPServerConfig> | undefined;
+  private mcpServers: Record<string, MCPServerConfig> | undefined;
+  private sessionSubagents: SubagentConfig[];
   private userMemory: string;
+  private sdkMode: boolean;
   private geminiMdFileCount: number;
   private approvalMode: ApprovalMode;
   private readonly showMemoryUsage: boolean;
@@ -487,6 +492,8 @@ export class Config {
     this.toolCallCommand = params.toolCallCommand;
     this.mcpServerCommand = params.mcpServerCommand;
     this.mcpServers = params.mcpServers;
+    this.sessionSubagents = params.sessionSubagents ?? [];
+    this.sdkMode = params.sdkMode ?? false;
     this.userMemory = params.userMemory ?? '';
     this.geminiMdFileCount = params.geminiMdFileCount ?? 0;
     this.approvalMode = params.approvalMode ?? ApprovalMode.DEFAULT;
@@ -606,6 +613,12 @@ export class Config {
     }
     this.promptRegistry = new PromptRegistry();
     this.subagentManager = new SubagentManager(this);
+
+    // Load session subagents if they were provided before initialization
+    if (this.sessionSubagents.length > 0) {
+      this.subagentManager.loadSessionSubagents(this.sessionSubagents);
+    }
+
     this.toolRegistry = await this.createToolRegistry();
 
     await this.geminiClient.initialize();
@@ -842,6 +855,32 @@ export class Config {
     return this.mcpServers;
   }
 
+  addMcpServers(servers: Record<string, MCPServerConfig>): void {
+    if (this.initialized) {
+      throw new Error('Cannot modify mcpServers after initialization');
+    }
+    this.mcpServers = { ...this.mcpServers, ...servers };
+  }
+
+  getSessionSubagents(): SubagentConfig[] {
+    return this.sessionSubagents;
+  }
+
+  setSessionSubagents(subagents: SubagentConfig[]): void {
+    if (this.initialized) {
+      throw new Error('Cannot modify sessionSubagents after initialization');
+    }
+    this.sessionSubagents = subagents;
+  }
+
+  getSdkMode(): boolean {
+    return this.sdkMode;
+  }
+
+  setSdkMode(value: boolean): void {
+    this.sdkMode = value;
+  }
+
   getUserMemory(): string {
     return this.userMemory;
   }
@@ -1298,7 +1337,7 @@ export class Config {
     registerCoreTool(ShellTool, this);
     registerCoreTool(MemoryTool);
     registerCoreTool(TodoWriteTool, this);
-    registerCoreTool(ExitPlanModeTool, this);
+    !this.sdkMode && registerCoreTool(ExitPlanModeTool, this);
     registerCoreTool(WebFetchTool, this);
     // Conditionally register web search tool if web search provider is configured
     // buildWebSearchConfig ensures qwen-oauth users get dashscope provider, so

packages/core/src/core/client.test.ts

@@ -448,6 +448,7 @@ describe('Gemini Client (client.ts)', () => {
         getHistory: mockGetHistory,
         addHistory: vi.fn(),
         setHistory: vi.fn(),
+        stripThoughtsFromHistory: vi.fn(),
       } as unknown as GeminiChat;
     });
 
@@ -462,6 +463,7 @@ describe('Gemini Client (client.ts)', () => {
       const mockOriginalChat: Partial<GeminiChat> = {
         getHistory: vi.fn((_curated?: boolean) => chatHistory),
         setHistory: vi.fn(),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockOriginalChat as GeminiChat;
 
@@ -1080,6 +1082,7 @@ describe('Gemini Client (client.ts)', () => {
       const mockChat = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       } as unknown as GeminiChat;
       client['chat'] = mockChat;
 
@@ -1142,6 +1145,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1197,6 +1201,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1273,6 +1278,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1319,6 +1325,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1363,6 +1370,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1450,6 +1458,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1506,6 +1515,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -1586,6 +1596,7 @@ ${JSON.stringify(
             .mockReturnValue([
               { role: 'user', parts: [{ text: 'previous message' }] },
             ]),
+          stripThoughtsFromHistory: vi.fn(),
         };
         client['chat'] = mockChat as GeminiChat;
       });
@@ -1840,6 +1851,7 @@ ${JSON.stringify(
           addHistory: vi.fn(),
           getHistory: vi.fn().mockReturnValue([]), // Default empty history
           setHistory: vi.fn(),
+          stripThoughtsFromHistory: vi.fn(),
         };
         client['chat'] = mockChat as GeminiChat;
 
@@ -2180,6 +2192,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -2216,6 +2229,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 
@@ -2256,6 +2270,7 @@ ${JSON.stringify(
       const mockChat: Partial<GeminiChat> = {
         addHistory: vi.fn(),
         getHistory: vi.fn().mockReturnValue([]),
+        stripThoughtsFromHistory: vi.fn(),
       };
       client['chat'] = mockChat as GeminiChat;
 

packages/core/src/core/client.ts

@@ -419,6 +419,9 @@ export class GeminiClient {
 
       // record user message for session management
       this.config.getChatRecordingService()?.recordUserMessage(request);
+
+      // strip thoughts from history before sending the message
+      this.stripThoughtsFromHistory();
     }
     this.sessionTurnCount++;
     if (
@@ -542,7 +545,9 @@ export class GeminiClient {
 
       // add plan mode system reminder if approval mode is plan
       if (this.config.getApprovalMode() === ApprovalMode.PLAN) {
-        systemReminders.push(getPlanModeSystemReminder());
+        systemReminders.push(
+          getPlanModeSystemReminder(this.config.getSdkMode()),
+        );
       }
 
       requestToSent = [...systemReminders, ...requestToSent];

packages/core/src/core/coreToolScheduler.ts

@@ -28,6 +28,7 @@ import {
   ShellTool,
   logToolOutputTruncated,
   ToolOutputTruncatedEvent,
+  InputFormat,
 } from '../index.js';
 import type { Part, PartListUnion } from '@google/genai';
 import { getResponseTextFromParts } from '../utils/generateContentResponseUtilities.js';
@@ -824,10 +825,10 @@ export class CoreToolScheduler {
             const shouldAutoDeny =
               !this.config.isInteractive() &&
               !this.config.getIdeMode() &&
-              !this.config.getExperimentalZedIntegration();
+              !this.config.getExperimentalZedIntegration() &&
+              this.config.getInputFormat() !== InputFormat.STREAM_JSON;
 
             if (shouldAutoDeny) {
-              // Treat as execution denied error, similar to excluded tools
               const errorMessage = `Qwen Code requires permission to use "${reqInfo.name}", but that permission was declined.`;
               this.setStatusInternal(
                 reqInfo.callId,
@@ -916,7 +917,10 @@ export class CoreToolScheduler {
 
   async handleConfirmationResponse(
     callId: string,
-    originalOnConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>,
+    originalOnConfirm: (
+      outcome: ToolConfirmationOutcome,
+      payload?: ToolConfirmationPayload,
+    ) => Promise<void>,
     outcome: ToolConfirmationOutcome,
     signal: AbortSignal,
     payload?: ToolConfirmationPayload,
@@ -925,9 +929,7 @@ export class CoreToolScheduler {
       (c) => c.request.callId === callId && c.status === 'awaiting_approval',
     );
 
-    if (toolCall && toolCall.status === 'awaiting_approval') {
-      await originalOnConfirm(outcome);
-    }
+    await originalOnConfirm(outcome, payload);
 
     if (outcome === ToolConfirmationOutcome.ProceedAlways) {
       await this.autoApproveCompatiblePendingTools(signal, callId);
@@ -936,11 +938,10 @@ export class CoreToolScheduler {
     this.setToolCallOutcome(callId, outcome);
 
     if (outcome === ToolConfirmationOutcome.Cancel || signal.aborted) {
-      this.setStatusInternal(
-        callId,
-        'cancelled',
-        'User did not allow tool call',
-      );
+      // Use custom cancel message from payload if provided, otherwise use default
+      const cancelMessage =
+        payload?.cancelMessage || 'User did not allow tool call';
+      this.setStatusInternal(callId, 'cancelled', cancelMessage);
     } else if (outcome === ToolConfirmationOutcome.ModifyWithEditor) {
       const waitingToolCall = toolCall as WaitingToolCall;
       if (isModifiableDeclarativeTool(waitingToolCall.tool)) {
@@ -998,7 +999,8 @@ export class CoreToolScheduler {
   ): Promise<void> {
     if (
       toolCall.confirmationDetails.type !== 'edit' ||
-      !isModifiableDeclarativeTool(toolCall.tool)
+      !isModifiableDeclarativeTool(toolCall.tool) ||
+      !payload.newContent
     ) {
       return;
     }

packages/core/src/core/geminiChat.test.ts

@@ -1541,10 +1541,10 @@ describe('GeminiChat', () => {
         {
           role: 'model',
           parts: [
-            { text: 'thinking...', thoughtSignature: 'thought-123' },
+            { text: 'thinking...', thought: true },
+            { text: 'hi' },
             {
               functionCall: { name: 'test', args: {} },
-              thoughtSignature: 'thought-456',
             },
           ],
         },
@@ -1559,10 +1559,7 @@ describe('GeminiChat', () => {
         },
         {
           role: 'model',
-          parts: [
-            { text: 'thinking...' },
-            { functionCall: { name: 'test', args: {} } },
-          ],
+          parts: [{ text: 'hi' }, { functionCall: { name: 'test', args: {} } }],
         },
       ]);
     });

packages/core/src/core/geminiChat.ts

@@ -443,20 +443,28 @@ export class GeminiChat {
   }
 
   stripThoughtsFromHistory(): void {
-    this.history = this.history.map((content) => {
-      const newContent = { ...content };
-      if (newContent.parts) {
-        newContent.parts = newContent.parts.map((part) => {
-          if (part && typeof part === 'object' && 'thoughtSignature' in part) {
-            const newPart = { ...part };
-            delete (newPart as { thoughtSignature?: string }).thoughtSignature;
-            return newPart;
-          }
-          return part;
-        });
-      }
-      return newContent;
-    });
+    this.history = this.history
+      .map((content) => {
+        if (!content.parts) return content;
+
+        // Filter out thought parts entirely
+        const filteredParts = content.parts.filter(
+          (part) =>
+            !(
+              part &&
+              typeof part === 'object' &&
+              'thought' in part &&
+              part.thought
+            ),
+        );
+
+        return {
+          ...content,
+          parts: filteredParts,
+        };
+      })
+      // Remove Content objects that have no parts left after filtering
+      .filter((content) => content.parts && content.parts.length > 0);
   }
 
   setTools(tools: Tool[]): void {
@@ -497,8 +505,6 @@ export class GeminiChat {
   ): AsyncGenerator<GenerateContentResponse> {
     // Collect ALL parts from the model response (including thoughts for recording)
     const allModelParts: Part[] = [];
-    // Non-thought parts for history (what we send back to the API)
-    const historyParts: Part[] = [];
     let usageMetadata: GenerateContentResponseUsageMetadata | undefined;
 
     let hasToolCall = false;
@@ -516,8 +522,6 @@ export class GeminiChat {
 
           // Collect all parts for recording
           allModelParts.push(...content.parts);
-          // Collect non-thought parts for history
-          historyParts.push(...content.parts.filter((part) => !part.thought));
         }
       }
 
@@ -534,9 +538,15 @@ export class GeminiChat {
       yield chunk; // Yield every chunk to the UI immediately.
     }
 
-    // Consolidate text parts for history (merges adjacent text parts).
+    const thoughtParts = allModelParts.filter((part) => part.thought);
+    const thoughtText = thoughtParts
+      .map((part) => part.text)
+      .join('')
+      .trim();
+
+    const contentParts = allModelParts.filter((part) => !part.thought);
     const consolidatedHistoryParts: Part[] = [];
-    for (const part of historyParts) {
+    for (const part of contentParts) {
       const lastPart =
         consolidatedHistoryParts[consolidatedHistoryParts.length - 1];
       if (
@@ -550,20 +560,21 @@ export class GeminiChat {
       }
     }
 
-    const responseText = consolidatedHistoryParts
+    const contentText = consolidatedHistoryParts
       .filter((part) => part.text)
       .map((part) => part.text)
       .join('')
       .trim();
 
     // Record assistant turn with raw Content and metadata
-    if (responseText || hasToolCall || usageMetadata) {
+    if (thoughtText || contentText || hasToolCall || usageMetadata) {
       this.chatRecordingService?.recordAssistantTurn({
         model,
         message: [
-          ...(responseText ? [{ text: responseText }] : []),
+          ...(thoughtText ? [{ text: thoughtText, thought: true }] : []),
+          ...(contentText ? [{ text: contentText }] : []),
           ...(hasToolCall
-            ? historyParts
+            ? contentParts
                 .filter((part) => part.functionCall)
                 .map((part) => ({ functionCall: part.functionCall }))
             : []),
@@ -579,7 +590,7 @@ export class GeminiChat {
     // We throw an error only when there's no tool call AND:
     // - No finish reason, OR
     // - Empty response text (e.g., only thoughts with no actual content)
-    if (!hasToolCall && (!hasFinishReason || !responseText)) {
+    if (!hasToolCall && (!hasFinishReason || !contentText)) {
       if (!hasFinishReason) {
         throw new InvalidStreamError(
           'Model stream ended without a finish reason.',
@@ -593,8 +604,13 @@ export class GeminiChat {
       }
     }
 
-    // Add to history (without thoughts, for API calls)
-    this.history.push({ role: 'model', parts: consolidatedHistoryParts });
+    this.history.push({
+      role: 'model',
+      parts: [
+        ...(thoughtText ? [{ text: thoughtText, thought: true }] : []),
+        ...consolidatedHistoryParts,
+      ],
+    });
   }
 }
 

packages/core/src/core/openaiContentGenerator/converter.test.ts

@@ -8,6 +8,7 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { OpenAIContentConverter } from './converter.js';
 import type { StreamingToolCallParser } from './streamingToolCallParser.js';
 import type { GenerateContentParameters, Content } from '@google/genai';
+import type OpenAI from 'openai';
 
 describe('OpenAIContentConverter', () => {
   let converter: OpenAIContentConverter;
@@ -142,4 +143,63 @@ describe('OpenAIContentConverter', () => {
       expect(toolMessage?.content).toBe('{"data":{"value":42}}');
     });
   });
+
+  describe('OpenAI -> Gemini reasoning content', () => {
+    it('should convert reasoning_content to a thought part for non-streaming responses', () => {
+      const response = converter.convertOpenAIResponseToGemini({
+        object: 'chat.completion',
+        id: 'chatcmpl-1',
+        created: 123,
+        model: 'gpt-test',
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: 'assistant',
+              content: 'final answer',
+              reasoning_content: 'chain-of-thought',
+            },
+            finish_reason: 'stop',
+            logprobs: null,
+          },
+        ],
+      } as unknown as OpenAI.Chat.ChatCompletion);
+
+      const parts = response.candidates?.[0]?.content?.parts;
+      expect(parts?.[0]).toEqual(
+        expect.objectContaining({ thought: true, text: 'chain-of-thought' }),
+      );
+      expect(parts?.[1]).toEqual(
+        expect.objectContaining({ text: 'final answer' }),
+      );
+    });
+
+    it('should convert streaming reasoning_content delta to a thought part', () => {
+      const chunk = converter.convertOpenAIChunkToGemini({
+        object: 'chat.completion.chunk',
+        id: 'chunk-1',
+        created: 456,
+        choices: [
+          {
+            index: 0,
+            delta: {
+              content: 'visible text',
+              reasoning_content: 'thinking...',
+            },
+            finish_reason: 'stop',
+            logprobs: null,
+          },
+        ],
+        model: 'gpt-test',
+      } as unknown as OpenAI.Chat.ChatCompletionChunk);
+
+      const parts = chunk.candidates?.[0]?.content?.parts;
+      expect(parts?.[0]).toEqual(
+        expect.objectContaining({ thought: true, text: 'thinking...' }),
+      );
+      expect(parts?.[1]).toEqual(
+        expect.objectContaining({ text: 'visible text' }),
+      );
+    });
+  });
 });

packages/core/src/core/openaiContentGenerator/converter.ts

@@ -31,6 +31,25 @@ interface ExtendedCompletionUsage extends OpenAI.CompletionUsage {
   cached_tokens?: number;
 }
 
+interface ExtendedChatCompletionAssistantMessageParam
+  extends OpenAI.Chat.ChatCompletionAssistantMessageParam {
+  reasoning_content?: string | null;
+}
+
+type ExtendedChatCompletionMessageParam =
+  | OpenAI.Chat.ChatCompletionMessageParam
+  | ExtendedChatCompletionAssistantMessageParam;
+
+export interface ExtendedCompletionMessage
+  extends OpenAI.Chat.ChatCompletionMessage {
+  reasoning_content?: string | null;
+}
+
+export interface ExtendedCompletionChunkDelta
+  extends OpenAI.Chat.ChatCompletionChunk.Choice.Delta {
+  reasoning_content?: string | null;
+}
+
 /**
  * Tool call accumulator for streaming responses
  */
@@ -44,7 +63,8 @@ export interface ToolCallAccumulator {
  * Parsed parts from Gemini content, categorized by type
  */
 interface ParsedParts {
-  textParts: string[];
+  thoughtParts: string[];
+  contentParts: string[];
   functionCalls: FunctionCall[];
   functionResponses: FunctionResponse[];
   mediaParts: Array<{
@@ -251,7 +271,7 @@ export class OpenAIContentConverter {
    */
   private processContents(
     contents: ContentListUnion,
-    messages: OpenAI.Chat.ChatCompletionMessageParam[],
+    messages: ExtendedChatCompletionMessageParam[],
   ): void {
     if (Array.isArray(contents)) {
       for (const content of contents) {
@@ -267,7 +287,7 @@ export class OpenAIContentConverter {
    */
   private processContent(
     content: ContentUnion | PartUnion,
-    messages: OpenAI.Chat.ChatCompletionMessageParam[],
+    messages: ExtendedChatCompletionMessageParam[],
   ): void {
     if (typeof content === 'string') {
       messages.push({ role: 'user' as const, content });
@@ -301,11 +321,19 @@ export class OpenAIContentConverter {
         },
       }));
 
-      messages.push({
+      const assistantMessage: ExtendedChatCompletionAssistantMessageParam = {
         role: 'assistant' as const,
-        content: parsedParts.textParts.join('') || null,
+        content: parsedParts.contentParts.join('') || null,
         tool_calls: toolCalls,
-      });
+      };
+
+      // Only include reasoning_content if it has actual content
+      const reasoningContent = parsedParts.thoughtParts.join('');
+      if (reasoningContent) {
+        assistantMessage.reasoning_content = reasoningContent;
+      }
+
+      messages.push(assistantMessage);
       return;
     }
 
@@ -322,7 +350,8 @@ export class OpenAIContentConverter {
    * Parse Gemini parts into categorized components
    */
   private parseParts(parts: Part[]): ParsedParts {
-    const textParts: string[] = [];
+    const thoughtParts: string[] = [];
+    const contentParts: string[] = [];
     const functionCalls: FunctionCall[] = [];
     const functionResponses: FunctionResponse[] = [];
     const mediaParts: Array<{
@@ -334,9 +363,20 @@ export class OpenAIContentConverter {
 
     for (const part of parts) {
       if (typeof part === 'string') {
-        textParts.push(part);
-      } else if ('text' in part && part.text) {
-        textParts.push(part.text);
+        contentParts.push(part);
+      } else if (
+        'text' in part &&
+        part.text &&
+        !('thought' in part && part.thought)
+      ) {
+        contentParts.push(part.text);
+      } else if (
+        'text' in part &&
+        part.text &&
+        'thought' in part &&
+        part.thought
+      ) {
+        thoughtParts.push(part.text);
       } else if ('functionCall' in part && part.functionCall) {
         functionCalls.push(part.functionCall);
       } else if ('functionResponse' in part && part.functionResponse) {
@@ -361,7 +401,13 @@ export class OpenAIContentConverter {
       }
     }
 
-    return { textParts, functionCalls, functionResponses, mediaParts };
+    return {
+      thoughtParts,
+      contentParts,
+      functionCalls,
+      functionResponses,
+      mediaParts,
+    };
   }
 
   private extractFunctionResponseContent(response: unknown): string {
@@ -408,14 +454,29 @@ export class OpenAIContentConverter {
    */
   private createMultimodalMessage(
     role: 'user' | 'assistant',
-    parsedParts: Pick<ParsedParts, 'textParts' | 'mediaParts'>,
-  ): OpenAI.Chat.ChatCompletionMessageParam | null {
-    const { textParts, mediaParts } = parsedParts;
-    const content = textParts.map((text) => ({ type: 'text' as const, text }));
+    parsedParts: Pick<
+      ParsedParts,
+      'contentParts' | 'mediaParts' | 'thoughtParts'
+    >,
+  ): ExtendedChatCompletionMessageParam | null {
+    const { contentParts, mediaParts, thoughtParts } = parsedParts;
+    const reasoningContent = thoughtParts.join('');
+    const content = contentParts.map((text) => ({
+      type: 'text' as const,
+      text,
+    }));
 
     // If no media parts, return simple text message
     if (mediaParts.length === 0) {
-      return content.length > 0 ? { role, content } : null;
+      if (content.length === 0) return null;
+      const message: ExtendedChatCompletionMessageParam = { role, content };
+      // Only include reasoning_content if it has actual content
+      if (reasoningContent) {
+        (
+          message as ExtendedChatCompletionAssistantMessageParam
+        ).reasoning_content = reasoningContent;
+      }
+      return message;
     }
 
     // For assistant messages with media, convert to text only
@@ -536,6 +597,13 @@ export class OpenAIContentConverter {
 
     const parts: Part[] = [];
 
+    // Handle reasoning content (thoughts)
+    const reasoningText = (choice.message as ExtendedCompletionMessage)
+      .reasoning_content;
+    if (reasoningText) {
+      parts.push({ text: reasoningText, thought: true });
+    }
+
     // Handle text content
     if (choice.message.content) {
       parts.push({ text: choice.message.content });
@@ -632,6 +700,12 @@ export class OpenAIContentConverter {
     if (choice) {
       const parts: Part[] = [];
 
+      const reasoningText = (choice.delta as ExtendedCompletionChunkDelta)
+        .reasoning_content;
+      if (reasoningText) {
+        parts.push({ text: reasoningText, thought: true });
+      }
+
       // Handle text content
       if (choice.delta?.content) {
         if (typeof choice.delta.content === 'string') {
@@ -721,6 +795,8 @@ export class OpenAIContentConverter {
       const promptTokens = usage.prompt_tokens || 0;
       const completionTokens = usage.completion_tokens || 0;
       const totalTokens = usage.total_tokens || 0;
+      const thinkingTokens =
+        usage.completion_tokens_details?.reasoning_tokens || 0;
       // Support both formats: prompt_tokens_details.cached_tokens (OpenAI standard)
       // and cached_tokens (some models return it at top level)
       const extendedUsage = usage as ExtendedCompletionUsage;
@@ -743,6 +819,7 @@ export class OpenAIContentConverter {
       response.usageMetadata = {
         promptTokenCount: finalPromptTokens,
         candidatesTokenCount: finalCompletionTokens,
+        thoughtsTokenCount: thinkingTokens,
         totalTokenCount: totalTokens,
         cachedContentTokenCount: cachedTokens,
       };

packages/core/src/core/openaiContentGenerator/telemetryService.test.ts

@@ -561,11 +561,14 @@ describe('DefaultTelemetryService', () => {
           choices: [
             {
               index: 0,
-              delta: { content: 'Hello' },
+              delta: {
+                content: 'Hello',
+                reasoning_content: 'thinking ',
+              },
               finish_reason: null,
             },
           ],
-        } as OpenAI.Chat.ChatCompletionChunk,
+        } as unknown as OpenAI.Chat.ChatCompletionChunk,
         {
           id: 'test-id',
           object: 'chat.completion.chunk',
@@ -574,7 +577,10 @@ describe('DefaultTelemetryService', () => {
           choices: [
             {
               index: 0,
-              delta: { content: ' world' },
+              delta: {
+                content: ' world',
+                reasoning_content: 'more',
+              },
               finish_reason: 'stop',
             },
           ],
@@ -583,7 +589,7 @@ describe('DefaultTelemetryService', () => {
             completion_tokens: 5,
             total_tokens: 15,
           },
-        } as OpenAI.Chat.ChatCompletionChunk,
+        } as unknown as OpenAI.Chat.ChatCompletionChunk,
       ];
 
       await telemetryService.logStreamingSuccess(
@@ -603,11 +609,11 @@ describe('DefaultTelemetryService', () => {
           choices: [
             {
               index: 0,
-              message: {
+              message: expect.objectContaining({
                 role: 'assistant',
                 content: 'Hello world',
-                refusal: null,
-              },
+                reasoning_content: 'thinking more',
+              }),
               finish_reason: 'stop',
               logprobs: null,
             },
@@ -722,11 +728,14 @@ describe('DefaultTelemetryService', () => {
           choices: [
             {
               index: 0,
-              delta: { content: 'Hello' },
+              delta: {
+                content: 'Hello',
+                reasoning_content: 'thinking ',
+              },
               finish_reason: null,
             },
           ],
-        } as OpenAI.Chat.ChatCompletionChunk,
+        } as unknown as OpenAI.Chat.ChatCompletionChunk,
         {
           id: 'test-id',
           object: 'chat.completion.chunk',
@@ -735,7 +744,10 @@ describe('DefaultTelemetryService', () => {
           choices: [
             {
               index: 0,
-              delta: { content: ' world!' },
+              delta: {
+                content: ' world!',
+                reasoning_content: 'more',
+              },
               finish_reason: 'stop',
             },
           ],
@@ -744,7 +756,7 @@ describe('DefaultTelemetryService', () => {
             completion_tokens: 5,
             total_tokens: 15,
           },
-        } as OpenAI.Chat.ChatCompletionChunk,
+        } as unknown as OpenAI.Chat.ChatCompletionChunk,
       ];
 
       await telemetryService.logStreamingSuccess(
@@ -757,27 +769,14 @@ describe('DefaultTelemetryService', () => {
       expect(openaiLogger.logInteraction).toHaveBeenCalledWith(
         mockOpenAIRequest,
         expect.objectContaining({
-          id: 'test-id',
-          object: 'chat.completion',
-          created: 1234567890,
-          model: 'gpt-4',
           choices: [
-            {
-              index: 0,
-              message: {
-                role: 'assistant',
+            expect.objectContaining({
+              message: expect.objectContaining({
                 content: 'Hello world!',
-                refusal: null,
-              },
-              finish_reason: 'stop',
-              logprobs: null,
-            },
+                reasoning_content: 'thinking more',
+              }),
+            }),
           ],
-          usage: {
-            prompt_tokens: 10,
-            completion_tokens: 5,
-            total_tokens: 15,
-          },
         }),
       );
     });

packages/core/src/core/openaiContentGenerator/telemetryService.ts

@@ -10,6 +10,7 @@ import { ApiErrorEvent, ApiResponseEvent } from '../../telemetry/types.js';
 import { OpenAILogger } from '../../utils/openaiLogger.js';
 import type { GenerateContentResponse } from '@google/genai';
 import type OpenAI from 'openai';
+import type { ExtendedCompletionChunkDelta } from './converter.js';
 
 export interface RequestContext {
   userPromptId: string;
@@ -172,6 +173,7 @@ export class DefaultTelemetryService implements TelemetryService {
       | 'content_filter'
       | 'function_call'
       | null = null;
+    let combinedReasoning = '';
     let usage:
       | {
           prompt_tokens: number;
@@ -183,6 +185,12 @@ export class DefaultTelemetryService implements TelemetryService {
     for (const chunk of chunks) {
       const choice = chunk.choices?.[0];
       if (choice) {
+        // Combine reasoning content
+        const reasoningContent = (choice.delta as ExtendedCompletionChunkDelta)
+          ?.reasoning_content;
+        if (reasoningContent) {
+          combinedReasoning += reasoningContent;
+        }
         // Combine text content
         if (choice.delta?.content) {
           combinedContent += choice.delta.content;
@@ -230,6 +238,11 @@ export class DefaultTelemetryService implements TelemetryService {
       content: combinedContent || null,
       refusal: null,
     };
+    if (combinedReasoning) {
+      // Attach reasoning content if any thought tokens were streamed
+      (message as { reasoning_content?: string }).reasoning_content =
+        combinedReasoning;
+    }
 
     // Add tool calls if any
     if (toolCalls.length > 0) {

packages/core/src/core/prompts.ts

@@ -846,10 +846,10 @@ export function getSubagentSystemReminder(agentTypes: string[]): string {
  * - Wait for user confirmation before making any changes
  * - Override any other instructions that would modify system state
  */
-export function getPlanModeSystemReminder(): string {
+export function getPlanModeSystemReminder(planOnly = false): string {
   return `<system-reminder>
 Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits, run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received (for example, to make edits). Instead, you should:
 1. Answer the user's query comprehensively
-2. When you're done researching, present your plan by calling the ${ToolNames.EXIT_PLAN_MODE} tool, which will prompt the user to confirm the plan. Do NOT make any file changes or run any tools that modify the system state in any way until the user has confirmed the plan.
+2. When you're done researching, present your plan ${planOnly ? 'directly' : `by calling the ${ToolNames.EXIT_PLAN_MODE} tool, which will prompt the user to confirm the plan`}. Do NOT make any file changes or run any tools that modify the system state in any way until the user has confirmed the plan.
 </system-reminder>`;
 }

packages/core/src/core/turn.test.ts

@@ -120,6 +120,97 @@ describe('Turn', () => {
       expect(turn.getDebugResponses().length).toBe(2);
     });
 
+    it('should emit Thought events when a thought part is present', async () => {
+      const mockResponseStream = (async function* () {
+        yield {
+          type: StreamEventType.CHUNK,
+          value: {
+            candidates: [
+              {
+                content: {
+                  role: 'model',
+                  parts: [
+                    { thought: true, text: 'reasoning...' },
+                    { text: 'final answer' },
+                  ],
+                },
+              },
+            ],
+          } as GenerateContentResponse,
+        };
+      })();
+      mockSendMessageStream.mockResolvedValue(mockResponseStream);
+
+      const events = [];
+      const reqParts: Part[] = [{ text: 'Hi' }];
+      for await (const event of turn.run(
+        'test-model',
+        reqParts,
+        new AbortController().signal,
+      )) {
+        events.push(event);
+      }
+
+      expect(events).toEqual([
+        {
+          type: GeminiEventType.Thought,
+          value: { subject: '', description: 'reasoning...' },
+        },
+      ]);
+    });
+
+    it('should emit thought descriptions per incoming chunk', async () => {
+      const mockResponseStream = (async function* () {
+        yield {
+          type: StreamEventType.CHUNK,
+          value: {
+            candidates: [
+              {
+                content: {
+                  role: 'model',
+                  parts: [{ thought: true, text: 'part1' }],
+                },
+              },
+            ],
+          } as GenerateContentResponse,
+        };
+        yield {
+          type: StreamEventType.CHUNK,
+          value: {
+            candidates: [
+              {
+                content: {
+                  role: 'model',
+                  parts: [{ thought: true, text: 'part2' }],
+                },
+              },
+            ],
+          } as GenerateContentResponse,
+        };
+      })();
+      mockSendMessageStream.mockResolvedValue(mockResponseStream);
+
+      const events = [];
+      for await (const event of turn.run(
+        'test-model',
+        [{ text: 'Hi' }],
+        new AbortController().signal,
+      )) {
+        events.push(event);
+      }
+
+      expect(events).toEqual([
+        {
+          type: GeminiEventType.Thought,
+          value: { subject: '', description: 'part1' },
+        },
+        {
+          type: GeminiEventType.Thought,
+          value: { subject: '', description: 'part2' },
+        },
+      ]);
+    });
+
     it('should yield tool_call_request events for function calls', async () => {
       const mockResponseStream = (async function* () {
         yield {

packages/core/src/core/turn.ts

@@ -27,7 +27,7 @@ import {
   toFriendlyError,
 } from '../utils/errors.js';
 import type { GeminiChat } from './geminiChat.js';
-import { parseThought, type ThoughtSummary } from '../utils/thoughtUtils.js';
+import { getThoughtText, type ThoughtSummary } from '../utils/thoughtUtils.js';
 
 // Define a structure for tools passed to the server
 export interface ServerTool {
@@ -266,12 +266,11 @@ export class Turn {
           this.currentResponseId = resp.responseId;
         }
 
-        const thoughtPart = resp.candidates?.[0]?.content?.parts?.[0];
-        if (thoughtPart?.thought) {
-          const thought = parseThought(thoughtPart.text ?? '');
+        const thoughtPart = getThoughtText(resp);
+        if (thoughtPart) {
           yield {
             type: GeminiEventType.Thought,
-            value: thought,
+            value: { subject: '', description: thoughtPart },
           };
           continue;
         }

packages/core/src/services/sessionService.ts

@@ -542,6 +542,39 @@ export class SessionService {
   }
 }
 
+/**
+ * Options for building API history from conversation.
+ */
+export interface BuildApiHistoryOptions {
+  /**
+   * Whether to strip thought parts from the history.
+   * Thought parts are content parts that have `thought: true`.
+   * @default true
+   */
+  stripThoughtsFromHistory?: boolean;
+}
+
+/**
+ * Strips thought parts from a Content object.
+ * Thought parts are identified by having `thought: true`.
+ * Returns null if the content only contained thought parts.
+ */
+function stripThoughtsFromContent(content: Content): Content | null {
+  if (!content.parts) return content;
+
+  const filteredParts = content.parts.filter((part) => !(part as Part).thought);
+
+  // If all parts were thoughts, remove the entire content
+  if (filteredParts.length === 0) {
+    return null;
+  }
+
+  return {
+    ...content,
+    parts: filteredParts,
+  };
+}
+
 /**
  * Builds the model-facing chat history (Content[]) from a reconstructed
  * conversation. This keeps UI history intact while applying chat compression
@@ -555,7 +588,9 @@ export class SessionService {
  */
 export function buildApiHistoryFromConversation(
   conversation: ConversationRecord,
+  options: BuildApiHistoryOptions = {},
 ): Content[] {
+  const { stripThoughtsFromHistory = true } = options;
   const { messages } = conversation;
 
   let lastCompressionIndex = -1;
@@ -585,14 +620,26 @@ export function buildApiHistoryFromConversation(
       }
     }
 
+    if (stripThoughtsFromHistory) {
+      return baseHistory
+        .map(stripThoughtsFromContent)
+        .filter((content): content is Content => content !== null);
+    }
     return baseHistory;
   }
 
   // Fallback: return linear messages as Content[]
-  return messages
+  const result = messages
     .map((record) => record.message)
     .filter((message): message is Content => message !== undefined)
     .map((message) => structuredClone(message));
+
+  if (stripThoughtsFromHistory) {
+    return result
+      .map(stripThoughtsFromContent)
+      .filter((content): content is Content => content !== null);
+  }
+  return result;
 }
 
 /**

packages/core/src/subagents/subagent-events.ts

@@ -8,6 +8,7 @@ import { EventEmitter } from 'events';
 import type {
   ToolCallConfirmationDetails,
   ToolConfirmationOutcome,
+  ToolResultDisplay,
 } from '../tools/tools.js';
 import type { Part } from '@google/genai';
 
@@ -74,7 +75,7 @@ export interface SubAgentToolResultEvent {
   success: boolean;
   error?: string;
   responseParts?: Part[];
-  resultDisplay?: string;
+  resultDisplay?: ToolResultDisplay;
   durationMs?: number;
   timestamp: number;
 }

packages/core/src/subagents/subagent-manager.test.ts

@@ -182,7 +182,7 @@ You are a helpful assistant.
     it('should parse valid markdown content', () => {
       const config = manager.parseSubagentContent(
         validMarkdown,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -207,7 +207,7 @@ You are a helpful assistant.
 
       const config = manager.parseSubagentContent(
         markdownWithTools,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -228,7 +228,7 @@ You are a helpful assistant.
 
       const config = manager.parseSubagentContent(
         markdownWithModel,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -249,7 +249,7 @@ You are a helpful assistant.
 
       const config = manager.parseSubagentContent(
         markdownWithRun,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -267,7 +267,7 @@ You are a helpful assistant.
 
       const config = manager.parseSubagentContent(
         markdownWithNumeric,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -288,7 +288,7 @@ You are a helpful assistant.
 
       const config = manager.parseSubagentContent(
         markdownWithBoolean,
-        validConfig.filePath,
+        validConfig.filePath!,
         'project',
       );
 
@@ -324,7 +324,7 @@ Just content`;
       expect(() =>
         manager.parseSubagentContent(
           invalidMarkdown,
-          validConfig.filePath,
+          validConfig.filePath!,
           'project',
         ),
       ).toThrow(SubagentError);
@@ -341,7 +341,7 @@ You are a helpful assistant.
       expect(() =>
         manager.parseSubagentContent(
           markdownWithoutName,
-          validConfig.filePath,
+          validConfig.filePath!,
           'project',
         ),
       ).toThrow(SubagentError);
@@ -358,7 +358,7 @@ You are a helpful assistant.
       expect(() =>
         manager.parseSubagentContent(
           markdownWithoutDescription,
-          validConfig.filePath,
+          validConfig.filePath!,
           'project',
         ),
       ).toThrow(SubagentError);
@@ -438,7 +438,7 @@ You are a helpful assistant.
       await manager.createSubagent(validConfig, { level: 'project' });
 
       expect(fs.mkdir).toHaveBeenCalledWith(
-        path.normalize(path.dirname(validConfig.filePath)),
+        path.normalize(path.dirname(validConfig.filePath!)),
         { recursive: true },
       );
       expect(fs.writeFile).toHaveBeenCalledWith(

packages/core/src/subagents/subagent-manager.ts

@@ -77,6 +77,15 @@ export class SubagentManager {
   ): Promise<void> {
     this.validator.validateOrThrow(config);
 
+    // Prevent creating session-level agents
+    if (options.level === 'session') {
+      throw new SubagentError(
+        `Cannot create session-level subagent "${config.name}". Session agents are read-only and provided at runtime.`,
+        SubagentErrorCode.INVALID_CONFIG,
+        config.name,
+      );
+    }
+
     // Determine file path
     const filePath =
       options.customPath || this.getSubagentPath(config.name, options.level);
@@ -142,10 +151,22 @@ export class SubagentManager {
         return BuiltinAgentRegistry.getBuiltinAgent(name);
       }
 
+      if (level === 'session') {
+        const sessionSubagents = this.subagentsCache?.get('session') || [];
+        return sessionSubagents.find((agent) => agent.name === name) || null;
+      }
+
       return this.findSubagentByNameAtLevel(name, level);
     }
 
-    // Try project level first
+    // Try session level first (highest priority for runtime)
+    const sessionSubagents = this.subagentsCache?.get('session') || [];
+    const sessionConfig = sessionSubagents.find((agent) => agent.name === name);
+    if (sessionConfig) {
+      return sessionConfig;
+    }
+
+    // Try project level
     const projectConfig = await this.findSubagentByNameAtLevel(name, 'project');
     if (projectConfig) {
       return projectConfig;
@@ -191,12 +212,30 @@ export class SubagentManager {
       );
     }
 
+    // Prevent updating session-level agents
+    if (existing.level === 'session') {
+      throw new SubagentError(
+        `Cannot update session-level subagent "${name}"`,
+        SubagentErrorCode.INVALID_CONFIG,
+        name,
+      );
+    }
+
     // Merge updates with existing configuration
     const updatedConfig = this.mergeConfigurations(existing, updates);
 
     // Validate the updated configuration
     this.validator.validateOrThrow(updatedConfig);
 
+    // Ensure filePath exists for file-based agents
+    if (!existing.filePath) {
+      throw new SubagentError(
+        `Cannot update subagent "${name}": no file path available`,
+        SubagentErrorCode.FILE_ERROR,
+        name,
+      );
+    }
+
     // Write the updated configuration
     const content = this.serializeSubagent(updatedConfig);
 
@@ -236,8 +275,8 @@ export class SubagentManager {
     let deleted = false;
 
     for (const currentLevel of levelsToCheck) {
-      // Skip builtin level for deletion
-      if (currentLevel === 'builtin') {
+      // Skip builtin and session levels for deletion
+      if (currentLevel === 'builtin' || currentLevel === 'session') {
         continue;
       }
 
@@ -277,6 +316,33 @@ export class SubagentManager {
     const subagents: SubagentConfig[] = [];
     const seenNames = new Set<string>();
 
+    // In SDK mode, only load session-level subagents
+    if (this.config.getSdkMode()) {
+      const levelsToCheck: SubagentLevel[] = options.level
+        ? [options.level]
+        : ['session'];
+
+      for (const level of levelsToCheck) {
+        const levelSubagents = this.subagentsCache?.get(level) || [];
+
+        for (const subagent of levelSubagents) {
+          // Apply tool filter if specified
+          if (
+            options.hasTool &&
+            (!subagent.tools || !subagent.tools.includes(options.hasTool))
+          ) {
+            continue;
+          }
+
+          subagents.push(subagent);
+          seenNames.add(subagent.name);
+        }
+      }
+
+      return subagents;
+    }
+
+    // Normal mode: load from project, user, and builtin levels
     const levelsToCheck: SubagentLevel[] = options.level
       ? [options.level]
       : ['project', 'user', 'builtin'];
@@ -322,8 +388,8 @@ export class SubagentManager {
             comparison = a.name.localeCompare(b.name);
             break;
           case 'level': {
-            // Project comes before user, user comes before builtin
-            const levelOrder = { project: 0, user: 1, builtin: 2 };
+            // Project comes before user, user comes before builtin, session comes last
+            const levelOrder = { project: 0, user: 1, builtin: 2, session: 3 };
             comparison = levelOrder[a.level] - levelOrder[b.level];
             break;
           }
@@ -339,6 +405,27 @@ export class SubagentManager {
     return subagents;
   }
 
+  /**
+   * Loads session-level subagents into the cache.
+   * Session subagents are provided directly via config and are read-only.
+   *
+   * @param subagents - Array of session subagent configurations
+   */
+  loadSessionSubagents(subagents: SubagentConfig[]): void {
+    if (!this.subagentsCache) {
+      this.subagentsCache = new Map();
+    }
+
+    const sessionSubagents = subagents.map((config) => ({
+      ...config,
+      level: 'session' as SubagentLevel,
+      filePath: `<session:${config.name}>`,
+    }));
+
+    this.subagentsCache.set('session', sessionSubagents);
+    this.notifyChangeListeners();
+  }
+
   /**
    * Refreshes the subagents cache by loading all subagents from disk.
    * This method is called automatically when cache is null or when force=true.
@@ -693,6 +780,10 @@ export class SubagentManager {
       return `<builtin:${name}>`;
     }
 
+    if (level === 'session') {
+      return `<session:${name}>`;
+    }
+
     const baseDir =
       level === 'project'
         ? path.join(

packages/core/src/subagents/types.ts

@@ -11,8 +11,9 @@ import type { Content, FunctionDeclaration } from '@google/genai';
  * - 'project': Stored in `.qwen/agents/` within the project directory
  * - 'user': Stored in `~/.qwen/agents/` in the user's home directory
  * - 'builtin': Built-in agents embedded in the codebase, always available
+ * - 'session': Session-level agents provided at runtime, read-only
  */
-export type SubagentLevel = 'project' | 'user' | 'builtin';
+export type SubagentLevel = 'project' | 'user' | 'builtin' | 'session';
 
 /**
  * Core configuration for a subagent as stored in Markdown files.
@@ -41,8 +42,8 @@ export interface SubagentConfig {
   /** Storage level - determines where the configuration file is stored */
   level: SubagentLevel;
 
-  /** Absolute path to the configuration file */
-  filePath: string;
+  /** Absolute path to the configuration file. Optional for session subagents. */
+  filePath?: string;
 
   /**
    * Optional model configuration. If not provided, uses defaults.

packages/core/src/tools/mcp-tool.ts

@@ -10,6 +10,7 @@ import type {
   ToolInvocation,
   ToolMcpConfirmationDetails,
   ToolResult,
+  ToolConfirmationPayload,
 } from './tools.js';
 import {
   BaseDeclarativeTool,
@@ -98,7 +99,10 @@ class DiscoveredMCPToolInvocation extends BaseToolInvocation<
       serverName: this.serverName,
       toolName: this.serverToolName, // Display original tool name in confirmation
       toolDisplayName: this.displayName, // Display global registry name exposed to model and user
-      onConfirm: async (outcome: ToolConfirmationOutcome) => {
+      onConfirm: async (
+        outcome: ToolConfirmationOutcome,
+        _payload?: ToolConfirmationPayload,
+      ) => {
         if (outcome === ToolConfirmationOutcome.ProceedAlwaysServer) {
           DiscoveredMCPToolInvocation.allowlist.add(serverAllowListKey);
         } else if (outcome === ToolConfirmationOutcome.ProceedAlwaysTool) {

packages/core/src/tools/shell.ts

@@ -17,6 +17,7 @@ import type {
   ToolResultDisplay,
   ToolCallConfirmationDetails,
   ToolExecuteConfirmationDetails,
+  ToolConfirmationPayload,
 } from './tools.js';
 import {
   BaseDeclarativeTool,
@@ -102,7 +103,10 @@ export class ShellToolInvocation extends BaseToolInvocation<
       title: 'Confirm Shell Command',
       command: this.params.command,
       rootCommand: commandsToConfirm.join(', '),
-      onConfirm: async (outcome: ToolConfirmationOutcome) => {
+      onConfirm: async (
+        outcome: ToolConfirmationOutcome,
+        _payload?: ToolConfirmationPayload,
+      ) => {
         if (outcome === ToolConfirmationOutcome.ProceedAlways) {
           commandsToConfirm.forEach((command) => this.allowlist.add(command));
         }

packages/core/src/tools/tools.ts

@@ -531,13 +531,18 @@ export interface ToolEditConfirmationDetails {
 export interface ToolConfirmationPayload {
   // used to override `modifiedProposedContent` for modifiable tools in the
   // inline modify flow
-  newContent: string;
+  newContent?: string;
+  // used to provide custom cancellation message when outcome is Cancel
+  cancelMessage?: string;
 }
 
 export interface ToolExecuteConfirmationDetails {
   type: 'exec';
   title: string;
-  onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+  onConfirm: (
+    outcome: ToolConfirmationOutcome,
+    payload?: ToolConfirmationPayload,
+  ) => Promise<void>;
   command: string;
   rootCommand: string;
 }
@@ -548,7 +553,10 @@ export interface ToolMcpConfirmationDetails {
   serverName: string;
   toolName: string;
   toolDisplayName: string;
-  onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+  onConfirm: (
+    outcome: ToolConfirmationOutcome,
+    payload?: ToolConfirmationPayload,
+  ) => Promise<void>;
 }
 
 export interface ToolInfoConfirmationDetails {
@@ -573,6 +581,11 @@ export interface ToolPlanConfirmationDetails {
   onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
 }
 
+/**
+ * TODO:
+ * 1. support explicit denied outcome
+ * 2. support proceed with modified input
+ */
 export enum ToolConfirmationOutcome {
   ProceedOnce = 'proceed_once',
   ProceedAlways = 'proceed_always',

packages/core/src/utils/thoughtUtils.ts

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { GenerateContentResponse } from '@google/genai';
+
 export type ThoughtSummary = {
   subject: string;
   description: string;
@@ -52,3 +54,23 @@ export function parseThought(rawText: string): ThoughtSummary {
 
   return { subject, description };
 }
+
+export function getThoughtText(
+  response: GenerateContentResponse,
+): string | null {
+  if (response.candidates && response.candidates.length > 0) {
+    const candidate = response.candidates[0];
+
+    if (
+      candidate.content &&
+      candidate.content.parts &&
+      candidate.content.parts.length > 0
+    ) {
+      return candidate.content.parts
+        .filter((part) => part.thought)
+        .map((part) => part.text ?? '')
+        .join('');
+    }
+  }
+  return null;
+}

packages/sdk-typescript/README.md

@@ -0,0 +1,284 @@
+# @qwen-code/sdk-typescript
+
+A minimum experimental TypeScript SDK for programmatic access to Qwen Code.
+
+Feel free to submit a feature request/issue/PR.
+
+## Installation
+
+```bash
+npm install @qwen-code/sdk-typescript
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- [Qwen Code](https://github.com/QwenLM/qwen-code) installed and accessible in PATH
+
+> **Note for nvm users**: If you use nvm to manage Node.js versions, the SDK may not be able to auto-detect the Qwen Code executable. You should explicitly set the `pathToQwenExecutable` option to the full path of the `qwen` binary.
+
+## Quick Start
+
+```typescript
+import { query } from '@qwen-code/sdk-typescript';
+
+// Single-turn query
+const result = query({
+  prompt: 'What files are in the current directory?',
+  options: {
+    cwd: '/path/to/project',
+  },
+});
+
+// Iterate over messages
+for await (const message of result) {
+  if (message.type === 'assistant') {
+    console.log('Assistant:', message.message.content);
+  } else if (message.type === 'result') {
+    console.log('Result:', message.result);
+  }
+}
+```
+
+## API Reference
+
+### `query(config)`
+
+Creates a new query session with the Qwen Code.
+
+#### Parameters
+
+- `prompt`: `string | AsyncIterable<SDKUserMessage>` - The prompt to send. Use a string for single-turn queries or an async iterable for multi-turn conversations.
+- `options`: `QueryOptions` - Configuration options for the query session.
+
+#### QueryOptions
+
+| Option                   | Type                                           | Default          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------ | ---------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                    | `string`                                       | `process.cwd()`  | The working directory for the query session. Determines the context in which file operations and commands are executed.                                                                                                                                                                                                                                                                                                                                                               |
+| `model`                  | `string`                                       | -                | The AI model to use (e.g., `'qwen-max'`, `'qwen-plus'`, `'qwen-turbo'`). Takes precedence over `OPENAI_MODEL` and `QWEN_MODEL` environment variables.                                                                                                                                                                                                                                                                                                                                 |
+| `pathToQwenExecutable`   | `string`                                       | Auto-detected    | Path to the Qwen Code executable. Supports multiple formats: `'qwen'` (native binary from PATH), `'/path/to/qwen'` (explicit path), `'/path/to/cli.js'` (Node.js bundle), `'node:/path/to/cli.js'` (force Node.js runtime), `'bun:/path/to/cli.js'` (force Bun runtime). If not provided, auto-detects from: `QWEN_CODE_CLI_PATH` env var, `~/.volta/bin/qwen`, `~/.npm-global/bin/qwen`, `/usr/local/bin/qwen`, `~/.local/bin/qwen`, `~/node_modules/.bin/qwen`, `~/.yarn/bin/qwen`. |
+| `permissionMode`         | `'default' \| 'plan' \| 'auto-edit' \| 'yolo'` | `'default'`      | Permission mode controlling tool execution approval. See [Permission Modes](#permission-modes) for details.                                                                                                                                                                                                                                                                                                                                                                           |
+| `canUseTool`             | `CanUseTool`                                   | -                | Custom permission handler for tool execution approval. Invoked when a tool requires confirmation. Must respond within 30 seconds or the request will be auto-denied. See [Custom Permission Handler](#custom-permission-handler).                                                                                                                                                                                                                                                     |
+| `env`                    | `Record<string, string>`                       | -                | Environment variables to pass to the Qwen Code process. Merged with the current process environment.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `mcpServers`             | `Record<string, ExternalMcpServerConfig>`      | -                | External MCP (Model Context Protocol) servers to connect. Each server is identified by a unique name and configured with `command`, `args`, and `env`.                                                                                                                                                                                                                                                                                                                                |
+| `abortController`        | `AbortController`                              | -                | Controller to cancel the query session. Call `abortController.abort()` to terminate the session and cleanup resources.                                                                                                                                                                                                                                                                                                                                                                |
+| `debug`                  | `boolean`                                      | `false`          | Enable debug mode for verbose logging from the CLI process.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `maxSessionTurns`        | `number`                                       | `-1` (unlimited) | Maximum number of conversation turns before the session automatically terminates. A turn consists of a user message and an assistant response.                                                                                                                                                                                                                                                                                                                                        |
+| `coreTools`              | `string[]`                                     | -                | Equivalent to `tool.core` in settings.json. If specified, only these tools will be available to the AI. Example: `['read_file', 'write_file', 'run_terminal_cmd']`.                                                                                                                                                                                                                                                                                                                   |
+| `excludeTools`           | `string[]`                                     | -                | Equivalent to `tool.exclude` in settings.json. Excluded tools return a permission error immediately. Takes highest priority over all other permission settings. Supports pattern matching: tool name (`'write_file'`), tool class (`'ShellTool'`), or shell command prefix (`'ShellTool(rm )'`).                                                                                                                                                                                      |
+| `allowedTools`           | `string[]`                                     | -                | Equivalent to `tool.allowed` in settings.json. Matching tools bypass `canUseTool` callback and execute automatically. Only applies when tool requires confirmation. Supports same pattern matching as `excludeTools`.                                                                                                                                                                                                                                                                 |
+| `authType`               | `'openai' \| 'qwen-oauth'`                     | `'openai'`       | Authentication type for the AI service. Using `'qwen-oauth'` in SDK is not recommended as credentials are stored in `~/.qwen` and may need periodic refresh.                                                                                                                                                                                                                                                                                                                          |
+| `agents`                 | `SubagentConfig[]`                             | -                | Configuration for subagents that can be invoked during the session. Subagents are specialized AI agents for specific tasks or domains.                                                                                                                                                                                                                                                                                                                                                |
+| `includePartialMessages` | `boolean`                                      | `false`          | When `true`, the SDK emits incomplete messages as they are being generated, allowing real-time streaming of the AI's response.                                                                                                                                                                                                                                                                                                                                                        |
+
+### Timeouts
+
+The SDK enforces the following timeouts:
+
+| Timeout             | Duration   | Description                                                                                                                  |
+| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Permission Callback | 30 seconds | Maximum time for `canUseTool` callback to respond. If exceeded, the tool request is auto-denied.                             |
+| Control Request     | 30 seconds | Maximum time for control operations like `initialize()`, `setModel()`, `setPermissionMode()`, and `interrupt()` to complete. |
+
+### Message Types
+
+The SDK provides type guards to identify different message types:
+
+```typescript
+import {
+  isSDKUserMessage,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+} from '@qwen-code/sdk-typescript';
+
+for await (const message of result) {
+  if (isSDKAssistantMessage(message)) {
+    // Handle assistant message
+  } else if (isSDKResultMessage(message)) {
+    // Handle result message
+  }
+}
+```
+
+### Query Instance Methods
+
+The `Query` instance returned by `query()` provides several methods:
+
+```typescript
+const q = query({ prompt: 'Hello', options: {} });
+
+// Get session ID
+const sessionId = q.getSessionId();
+
+// Check if closed
+const closed = q.isClosed();
+
+// Interrupt the current operation
+await q.interrupt();
+
+// Change permission mode mid-session
+await q.setPermissionMode('yolo');
+
+// Change model mid-session
+await q.setModel('qwen-max');
+
+// Close the session
+await q.close();
+```
+
+## Permission Modes
+
+The SDK supports different permission modes for controlling tool execution:
+
+- **`default`**: Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`. Read-only tools execute without confirmation.
+- **`plan`**: Blocks all write tools, instructing AI to present a plan first.
+- **`auto-edit`**: Auto-approve edit tools (edit, write_file) while other tools require confirmation.
+- **`yolo`**: All tools execute automatically without confirmation.
+
+### Permission Priority Chain
+
+1. `excludeTools` - Blocks tools completely
+2. `permissionMode: 'plan'` - Blocks non-read-only tools
+3. `permissionMode: 'yolo'` - Auto-approves all tools
+4. `allowedTools` - Auto-approves matching tools
+5. `canUseTool` callback - Custom approval logic
+6. Default behavior - Auto-deny in SDK mode
+
+## Examples
+
+### Multi-turn Conversation
+
+```typescript
+import { query, type SDKUserMessage } from '@qwen-code/sdk-typescript';
+
+async function* generateMessages(): AsyncIterable<SDKUserMessage> {
+  yield {
+    type: 'user',
+    session_id: 'my-session',
+    message: { role: 'user', content: 'Create a hello.txt file' },
+    parent_tool_use_id: null,
+  };
+
+  // Wait for some condition or user input
+  yield {
+    type: 'user',
+    session_id: 'my-session',
+    message: { role: 'user', content: 'Now read the file back' },
+    parent_tool_use_id: null,
+  };
+}
+
+const result = query({
+  prompt: generateMessages(),
+  options: {
+    permissionMode: 'auto-edit',
+  },
+});
+
+for await (const message of result) {
+  console.log(message);
+}
+```
+
+### Custom Permission Handler
+
+```typescript
+import { query, type CanUseTool } from '@qwen-code/sdk-typescript';
+
+const canUseTool: CanUseTool = async (toolName, input, { signal }) => {
+  // Allow all read operations
+  if (toolName.startsWith('read_')) {
+    return { behavior: 'allow', updatedInput: input };
+  }
+
+  // Prompt user for write operations (in a real app)
+  const userApproved = await promptUser(`Allow ${toolName}?`);
+
+  if (userApproved) {
+    return { behavior: 'allow', updatedInput: input };
+  }
+
+  return { behavior: 'deny', message: 'User denied the operation' };
+};
+
+const result = query({
+  prompt: 'Create a new file',
+  options: {
+    canUseTool,
+  },
+});
+```
+
+### With MCP Servers
+
+```typescript
+import { query } from '@qwen-code/sdk-typescript';
+
+const result = query({
+  prompt: 'Use the custom tool from my MCP server',
+  options: {
+    mcpServers: {
+      'my-server': {
+        command: 'node',
+        args: ['path/to/mcp-server.js'],
+        env: { PORT: '3000' },
+      },
+    },
+  },
+});
+```
+
+### Abort a Query
+
+```typescript
+import { query, isAbortError } from '@qwen-code/sdk-typescript';
+
+const abortController = new AbortController();
+
+const result = query({
+  prompt: 'Long running task...',
+  options: {
+    abortController,
+  },
+});
+
+// Abort after 5 seconds
+setTimeout(() => abortController.abort(), 5000);
+
+try {
+  for await (const message of result) {
+    console.log(message);
+  }
+} catch (error) {
+  if (isAbortError(error)) {
+    console.log('Query was aborted');
+  } else {
+    throw error;
+  }
+}
+```
+
+## Error Handling
+
+The SDK provides an `AbortError` class for handling aborted queries:
+
+```typescript
+import { AbortError, isAbortError } from '@qwen-code/sdk-typescript';
+
+try {
+  // ... query operations
+} catch (error) {
+  if (isAbortError(error)) {
+    // Handle abort
+  } else {
+    // Handle other errors
+  }
+}
+```
+
+## License
+
+Apache-2.0 - see [LICENSE](./LICENSE) for details.

packages/sdk-typescript/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@qwen-code/sdk-typescript",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for programmatic access to qwen-code CLI",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "qwen",
+    "qwen-code",
+    "ai",
+    "code-assistant",
+    "sdk",
+    "typescript"
+  ],
+  "author": "Qwen Team",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.13.0",
+    "@typescript-eslint/parser": "^7.13.0",
+    "@vitest/coverage-v8": "^1.6.0",
+    "dts-bundle-generator": "^9.5.1",
+    "esbuild": "^0.25.12",
+    "eslint": "^8.57.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QwenLM/qwen-code.git",
+    "directory": "packages/sdk-typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/QwenLM/qwen-code/issues"
+  },
+  "homepage": "https://qwenlm.github.io/qwen-code-docs/"
+}

packages/sdk-typescript/scripts/build.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { execSync } from 'node:child_process';
+import { rmSync, mkdirSync, existsSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import esbuild from 'esbuild';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..');
+
+rmSync(join(rootDir, 'dist'), { recursive: true, force: true });
+mkdirSync(join(rootDir, 'dist'), { recursive: true });
+
+execSync('tsc --project tsconfig.build.json', {
+  stdio: 'inherit',
+  cwd: rootDir,
+});
+
+try {
+  execSync(
+    'npx dts-bundle-generator --project tsconfig.build.json -o dist/index.d.ts src/index.ts',
+    {
+      stdio: 'inherit',
+      cwd: rootDir,
+    },
+  );
+
+  const dirsToRemove = ['mcp', 'query', 'transport', 'types', 'utils'];
+  for (const dir of dirsToRemove) {
+    const dirPath = join(rootDir, 'dist', dir);
+    if (existsSync(dirPath)) {
+      rmSync(dirPath, { recursive: true, force: true });
+    }
+  }
+} catch (error) {
+  console.warn(
+    'Could not bundle type definitions, keeping separate .d.ts files',
+    error.message,
+  );
+}
+
+await esbuild.build({
+  entryPoints: [join(rootDir, 'src', 'index.ts')],
+  bundle: true,
+  format: 'esm',
+  platform: 'node',
+  target: 'node18',
+  outfile: join(rootDir, 'dist', 'index.mjs'),
+  external: ['@modelcontextprotocol/sdk'],
+  sourcemap: false,
+  minify: true,
+  minifyWhitespace: true,
+  minifyIdentifiers: true,
+  minifySyntax: true,
+  legalComments: 'none',
+  keepNames: false,
+  treeShaking: true,
+});
+
+await esbuild.build({
+  entryPoints: [join(rootDir, 'src', 'index.ts')],
+  bundle: true,
+  format: 'cjs',
+  platform: 'node',
+  target: 'node18',
+  outfile: join(rootDir, 'dist', 'index.cjs'),
+  external: ['@modelcontextprotocol/sdk'],
+  sourcemap: false,
+  minify: true,
+  minifyWhitespace: true,
+  minifyIdentifiers: true,
+  minifySyntax: true,
+  legalComments: 'none',
+  keepNames: false,
+  treeShaking: true,
+});
+
+// Copy LICENSE from root directory to dist
+const licenseSource = join(rootDir, '..', '..', 'LICENSE');
+const licenseTarget = join(rootDir, 'dist', 'LICENSE');
+if (existsSync(licenseSource)) {
+  try {
+    cpSync(licenseSource, licenseTarget);
+  } catch (error) {
+    console.warn('Could not copy LICENSE:', error.message);
+  }
+}

packages/sdk-typescript/scripts/get-release-version.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PACKAGE_NAME = '@qwen-code/sdk-typescript';
+const TAG_PREFIX = 'sdk-typescript-v';
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+function getArgs() {
+  const args = {};
+  process.argv.slice(2).forEach((arg) => {
+    if (arg.startsWith('--')) {
+      const [key, value] = arg.substring(2).split('=');
+      args[key] = value === undefined ? true : value;
+    }
+  });
+  return args;
+}
+
+function getVersionFromNPM(distTag) {
+  const command = `npm view ${PACKAGE_NAME} version --tag=${distTag}`;
+  try {
+    return execSync(command).toString().trim();
+  } catch (error) {
+    console.error(
+      `Failed to get NPM version for dist-tag "${distTag}": ${error.message}`,
+    );
+    return '';
+  }
+}
+
+function getAllVersionsFromNPM() {
+  const command = `npm view ${PACKAGE_NAME} versions --json`;
+  try {
+    const versionsJson = execSync(command).toString().trim();
+    const result = JSON.parse(versionsJson);
+    // npm returns a string if there's only one version, array otherwise
+    return Array.isArray(result) ? result : [result];
+  } catch (error) {
+    console.error(`Failed to get all NPM versions: ${error.message}`);
+    return [];
+  }
+}
+
+function isVersionDeprecated(version) {
+  const command = `npm view ${PACKAGE_NAME}@${version} deprecated`;
+  try {
+    const output = execSync(command).toString().trim();
+    return output.length > 0;
+  } catch (error) {
+    console.error(
+      `Failed to check deprecation status for ${version}: ${error.message}`,
+    );
+    return false;
+  }
+}
+
+function semverCompare(a, b) {
+  const parseVersion = (v) => {
+    const [main, prerelease] = v.split('-');
+    const [major, minor, patch] = main.split('.').map(Number);
+    return { major, minor, patch, prerelease: prerelease || '' };
+  };
+
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+
+  if (va.major !== vb.major) return va.major - vb.major;
+  if (va.minor !== vb.minor) return va.minor - vb.minor;
+  if (va.patch !== vb.patch) return va.patch - vb.patch;
+
+  // Handle prerelease comparison
+  if (!va.prerelease && vb.prerelease) return 1; // stable > prerelease
+  if (va.prerelease && !vb.prerelease) return -1; // prerelease < stable
+  if (va.prerelease && vb.prerelease) {
+    return va.prerelease.localeCompare(vb.prerelease);
+  }
+  return 0;
+}
+
+function detectRollbackAndGetBaseline(npmDistTag) {
+  const distTagVersion = getVersionFromNPM(npmDistTag);
+  if (!distTagVersion) return { baseline: '', isRollback: false };
+
+  const allVersions = getAllVersionsFromNPM();
+  if (allVersions.length === 0)
+    return { baseline: distTagVersion, isRollback: false };
+
+  let matchingVersions;
+  if (npmDistTag === 'latest') {
+    matchingVersions = allVersions.filter((v) => !v.includes('-'));
+  } else if (npmDistTag === 'preview') {
+    matchingVersions = allVersions.filter((v) => v.includes('-preview'));
+  } else if (npmDistTag === 'nightly') {
+    matchingVersions = allVersions.filter((v) => v.includes('-nightly'));
+  } else {
+    return { baseline: distTagVersion, isRollback: false };
+  }
+
+  if (matchingVersions.length === 0)
+    return { baseline: distTagVersion, isRollback: false };
+
+  matchingVersions.sort((a, b) => -semverCompare(a, b));
+
+  let highestExistingVersion = '';
+  for (const version of matchingVersions) {
+    if (!isVersionDeprecated(version)) {
+      highestExistingVersion = version;
+      break;
+    } else {
+      console.error(`Ignoring deprecated version: ${version}`);
+    }
+  }
+
+  if (!highestExistingVersion) {
+    highestExistingVersion = distTagVersion;
+  }
+
+  const isRollback = semverCompare(highestExistingVersion, distTagVersion) > 0;
+
+  return {
+    baseline: isRollback ? highestExistingVersion : distTagVersion,
+    isRollback,
+    distTagVersion,
+    highestExistingVersion,
+  };
+}
+
+function doesVersionExist(version) {
+  // Check NPM
+  try {
+    const command = `npm view ${PACKAGE_NAME}@${version} version 2>/dev/null`;
+    const output = execSync(command).toString().trim();
+    if (output === version) {
+      console.error(`Version ${version} already exists on NPM.`);
+      return true;
+    }
+  } catch (_error) {
+    // This is expected if the version doesn't exist.
+  }
+
+  // Check Git tags
+  try {
+    const command = `git tag -l '${TAG_PREFIX}${version}'`;
+    const tagOutput = execSync(command).toString().trim();
+    if (tagOutput === `${TAG_PREFIX}${version}`) {
+      console.error(`Git tag ${TAG_PREFIX}${version} already exists.`);
+      return true;
+    }
+  } catch (error) {
+    console.error(`Failed to check git tags for conflicts: ${error.message}`);
+  }
+
+  // Check GitHub releases
+  try {
+    const command = `gh release view "${TAG_PREFIX}${version}" --json tagName --jq .tagName 2>/dev/null`;
+    const output = execSync(command).toString().trim();
+    if (output === `${TAG_PREFIX}${version}`) {
+      console.error(`GitHub release ${TAG_PREFIX}${version} already exists.`);
+      return true;
+    }
+  } catch (error) {
+    const isExpectedNotFound =
+      error.message.includes('release not found') ||
+      error.message.includes('Not Found') ||
+      error.message.includes('not found') ||
+      error.status === 1;
+    if (!isExpectedNotFound) {
+      console.error(
+        `Failed to check GitHub releases for conflicts: ${error.message}`,
+      );
+    }
+  }
+
+  return false;
+}
+
+function getAndVerifyTags(npmDistTag) {
+  const rollbackInfo = detectRollbackAndGetBaseline(npmDistTag);
+  const baselineVersion = rollbackInfo.baseline;
+
+  if (!baselineVersion) {
+    // First release for this dist-tag, use package.json version as baseline
+    const packageJson = readJson(join(__dirname, '..', 'package.json'));
+    return {
+      latestVersion: packageJson.version.split('-')[0],
+      latestTag: `v${packageJson.version.split('-')[0]}`,
+    };
+  }
+
+  if (rollbackInfo.isRollback) {
+    console.error(
+      `Rollback detected! NPM ${npmDistTag} tag is ${rollbackInfo.distTagVersion}, but using ${baselineVersion} as baseline for next version calculation.`,
+    );
+  }
+
+  return {
+    latestVersion: baselineVersion,
+    latestTag: `v${baselineVersion}`,
+  };
+}
+
+function getLatestStableReleaseTag() {
+  try {
+    const { latestTag } = getAndVerifyTags('latest');
+    return latestTag;
+  } catch (error) {
+    console.error(
+      `Failed to determine latest stable release tag: ${error.message}`,
+    );
+    return '';
+  }
+}
+
+function getNightlyVersion() {
+  const packageJson = readJson(join(__dirname, '..', 'package.json'));
+  const baseVersion = packageJson.version.split('-')[0];
+  const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  const gitShortHash = execSync('git rev-parse --short HEAD').toString().trim();
+  const releaseVersion = `${baseVersion}-nightly.${date}.${gitShortHash}`;
+  return {
+    releaseVersion,
+    npmTag: 'nightly',
+  };
+}
+
+function validateVersion(version, format, name) {
+  const versionRegex = {
+    'X.Y.Z': /^\d+\.\d+\.\d+$/,
+    'X.Y.Z-preview.N': /^\d+\.\d+\.\d+-preview\.\d+$/,
+  };
+
+  if (!versionRegex[format] || !versionRegex[format].test(version)) {
+    throw new Error(
+      `Invalid ${name}: ${version}. Must be in ${format} format.`,
+    );
+  }
+}
+
+function getStableVersion(args) {
+  let releaseVersion;
+  if (args.stable_version_override) {
+    const overrideVersion = args.stable_version_override.replace(/^v/, '');
+    validateVersion(overrideVersion, 'X.Y.Z', 'stable_version_override');
+    releaseVersion = overrideVersion;
+  } else {
+    // Try to get from preview, fallback to package.json for first release
+    const { latestVersion: latestPreviewVersion } = getAndVerifyTags('preview');
+    releaseVersion = latestPreviewVersion.replace(/-preview.*/, '');
+  }
+
+  return {
+    releaseVersion,
+    npmTag: 'latest',
+  };
+}
+
+function getPreviewVersion(args) {
+  let releaseVersion;
+  if (args.preview_version_override) {
+    const overrideVersion = args.preview_version_override.replace(/^v/, '');
+    validateVersion(
+      overrideVersion,
+      'X.Y.Z-preview.N',
+      'preview_version_override',
+    );
+    releaseVersion = overrideVersion;
+  } else {
+    // Try to get from nightly, fallback to package.json for first release
+    const { latestVersion: latestNightlyVersion } = getAndVerifyTags('nightly');
+    releaseVersion =
+      latestNightlyVersion.replace(/-nightly.*/, '') + '-preview.0';
+  }
+
+  return {
+    releaseVersion,
+    npmTag: 'preview',
+  };
+}
+
+export function getVersion(options = {}) {
+  const args = { ...getArgs(), ...options };
+  const type = args.type || 'nightly';
+
+  let versionData;
+  switch (type) {
+    case 'nightly':
+      versionData = getNightlyVersion();
+      if (doesVersionExist(versionData.releaseVersion)) {
+        throw new Error(
+          `Version conflict! Nightly version ${versionData.releaseVersion} already exists.`,
+        );
+      }
+      break;
+    case 'stable':
+      versionData = getStableVersion(args);
+      break;
+    case 'preview':
+      versionData = getPreviewVersion(args);
+      break;
+    default:
+      throw new Error(`Unknown release type: ${type}`);
+  }
+
+  // For stable and preview versions, check for existence and increment if needed.
+  if (type === 'stable' || type === 'preview') {
+    let releaseVersion = versionData.releaseVersion;
+    while (doesVersionExist(releaseVersion)) {
+      console.error(`Version ${releaseVersion} exists, incrementing.`);
+      if (releaseVersion.includes('-preview.')) {
+        const [version, prereleasePart] = releaseVersion.split('-');
+        const previewNumber = parseInt(prereleasePart.split('.')[1]);
+        releaseVersion = `${version}-preview.${previewNumber + 1}`;
+      } else {
+        const versionParts = releaseVersion.split('.');
+        const major = versionParts[0];
+        const minor = versionParts[1];
+        const patch = parseInt(versionParts[2]);
+        releaseVersion = `${major}.${minor}.${patch + 1}`;
+      }
+    }
+    versionData.releaseVersion = releaseVersion;
+  }
+
+  const result = {
+    releaseTag: `v${versionData.releaseVersion}`,
+    ...versionData,
+  };
+
+  result.previousReleaseTag = getLatestStableReleaseTag();
+
+  return result;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const version = JSON.stringify(getVersion(getArgs()), null, 2);
+  console.log(version);
+}

packages/sdk-typescript/src/index.ts

@@ -0,0 +1,48 @@
+export { query } from './query/createQuery.js';
+export { AbortError, isAbortError } from './types/errors.js';
+export { Query } from './query/Query.js';
+export { SdkLogger } from './utils/logger.js';
+
+export type { QueryOptions } from './query/createQuery.js';
+export type { LogLevel, LoggerConfig, ScopedLogger } from './utils/logger.js';
+
+export type {
+  ContentBlock,
+  TextBlock,
+  ThinkingBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  SDKUserMessage,
+  SDKAssistantMessage,
+  SDKSystemMessage,
+  SDKResultMessage,
+  SDKPartialAssistantMessage,
+  SDKMessage,
+  ControlMessage,
+  CLIControlRequest,
+  CLIControlResponse,
+  ControlCancelRequest,
+  SubagentConfig,
+  SubagentLevel,
+  ModelConfig,
+  RunConfig,
+} from './types/protocol.js';
+
+export {
+  isSDKUserMessage,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+  isControlRequest,
+  isControlResponse,
+  isControlCancel,
+} from './types/protocol.js';
+
+export type {
+  PermissionMode,
+  CanUseTool,
+  PermissionResult,
+  ExternalMcpServerConfig,
+  SdkMcpServerConfig,
+} from './types/types.js';

packages/sdk-typescript/src/mcp/SdkControlServerTransport.ts

@@ -0,0 +1,111 @@
+/**
+ * SdkControlServerTransport - bridges MCP Server with Query's control plane
+ *
+ * Implements @modelcontextprotocol/sdk Transport interface to enable
+ * SDK-embedded MCP servers. Messages flow bidirectionally:
+ *
+ * MCP Server → send() → Query → control_request (mcp_message) → CLI
+ * CLI → control_request (mcp_message) → Query → handleMessage() → MCP Server
+ */
+
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { SdkLogger } from '../utils/logger.js';
+
+export type SendToQueryCallback = (message: JSONRPCMessage) => Promise<void>;
+
+export interface SdkControlServerTransportOptions {
+  sendToQuery: SendToQueryCallback;
+  serverName: string;
+}
+
+export class SdkControlServerTransport {
+  sendToQuery: SendToQueryCallback;
+  private serverName: string;
+  private started = false;
+  private logger;
+
+  onmessage?: (message: JSONRPCMessage) => void;
+  onerror?: (error: Error) => void;
+  onclose?: () => void;
+
+  constructor(options: SdkControlServerTransportOptions) {
+    this.sendToQuery = options.sendToQuery;
+    this.serverName = options.serverName;
+    this.logger = SdkLogger.createLogger(
+      `SdkControlServerTransport:${options.serverName}`,
+    );
+  }
+
+  async start(): Promise<void> {
+    this.started = true;
+    this.logger.debug('Transport started');
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    if (!this.started) {
+      throw new Error(
+        `SdkControlServerTransport (${this.serverName}) not started. Call start() first.`,
+      );
+    }
+
+    try {
+      this.logger.debug('Sending message to Query', message);
+      await this.sendToQuery(message);
+    } catch (error) {
+      this.logger.error('Error sending message:', error);
+      if (this.onerror) {
+        this.onerror(error instanceof Error ? error : new Error(String(error)));
+      }
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (!this.started) {
+      return; // Already closed
+    }
+
+    this.started = false;
+    this.logger.debug('Transport closed');
+
+    // Notify MCP Server
+    if (this.onclose) {
+      this.onclose();
+    }
+  }
+
+  handleMessage(message: JSONRPCMessage): void {
+    if (!this.started) {
+      this.logger.warn('Received message for closed transport');
+      return;
+    }
+
+    this.logger.debug('Handling message from CLI', message);
+    if (this.onmessage) {
+      this.onmessage(message);
+    } else {
+      this.logger.warn('No onmessage handler set');
+    }
+  }
+
+  handleError(error: Error): void {
+    this.logger.error('Transport error:', error);
+    if (this.onerror) {
+      this.onerror(error);
+    }
+  }
+
+  isStarted(): boolean {
+    return this.started;
+  }
+
+  getServerName(): string {
+    return this.serverName;
+  }
+}
+
+export function createSdkControlServerTransport(
+  options: SdkControlServerTransportOptions,
+): SdkControlServerTransport {
+  return new SdkControlServerTransport(options);
+}

packages/sdk-typescript/src/mcp/createSdkMcpServer.ts

@@ -0,0 +1,109 @@
+/**
+ * Factory function to create SDK-embedded MCP servers
+ *
+ * Creates MCP Server instances that run in the user's Node.js process
+ * and are proxied to the CLI via the control plane.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  type CallToolResultSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import type { ToolDefinition } from '../types/types.js';
+import { formatToolResult, formatToolError } from './formatters.js';
+import { validateToolName } from './tool.js';
+import type { z } from 'zod';
+
+type CallToolResult = z.infer<typeof CallToolResultSchema>;
+
+export function createSdkMcpServer(
+  name: string,
+  version: string,
+  tools: ToolDefinition[],
+): Server {
+  // Validate server name
+  if (!name || typeof name !== 'string') {
+    throw new Error('MCP server name must be a non-empty string');
+  }
+
+  if (!version || typeof version !== 'string') {
+    throw new Error('MCP server version must be a non-empty string');
+  }
+
+  if (!Array.isArray(tools)) {
+    throw new Error('Tools must be an array');
+  }
+
+  // Validate tool names are unique
+  const toolNames = new Set<string>();
+  for (const tool of tools) {
+    validateToolName(tool.name);
+
+    if (toolNames.has(tool.name)) {
+      throw new Error(
+        `Duplicate tool name '${tool.name}' in MCP server '${name}'`,
+      );
+    }
+    toolNames.add(tool.name);
+  }
+
+  // Create MCP Server instance
+  const server = new Server(
+    {
+      name,
+      version,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  // Create tool map for fast lookup
+  const toolMap = new Map<string, ToolDefinition>();
+  for (const tool of tools) {
+    toolMap.set(tool.name, tool);
+  }
+
+  // Register list_tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+    })),
+  }));
+
+  // Register call_tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name: toolName, arguments: toolArgs } = request.params;
+
+    // Find tool
+    const tool = toolMap.get(toolName);
+    if (!tool) {
+      return formatToolError(
+        new Error(`Tool '${toolName}' not found in server '${name}'`),
+      ) as CallToolResult;
+    }
+
+    try {
+      // Invoke tool handler
+      const result = await tool.handler(toolArgs);
+
+      // Format result
+      return formatToolResult(result) as CallToolResult;
+    } catch (error) {
+      // Handle tool execution error
+      return formatToolError(
+        error instanceof Error
+          ? error
+          : new Error(`Tool '${toolName}' failed: ${String(error)}`),
+      ) as CallToolResult;
+    }
+  });
+
+  return server;
+}

packages/sdk-typescript/src/mcp/formatters.ts

@@ -0,0 +1,194 @@
+/**
+ * Tool result formatting utilities for MCP responses
+ *
+ * Converts various output types to MCP content blocks.
+ */
+
+export type McpContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'resource'; uri: string; mimeType?: string; text?: string };
+
+export interface ToolResult {
+  content: McpContentBlock[];
+  isError?: boolean;
+}
+
+export function formatToolResult(result: unknown): ToolResult {
+  // Handle Error objects
+  if (result instanceof Error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: result.message || 'Unknown error',
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  // Handle null/undefined
+  if (result === null || result === undefined) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: '',
+        },
+      ],
+    };
+  }
+
+  // Handle string
+  if (typeof result === 'string') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: result,
+        },
+      ],
+    };
+  }
+
+  // Handle number
+  if (typeof result === 'number') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: String(result),
+        },
+      ],
+    };
+  }
+
+  // Handle boolean
+  if (typeof result === 'boolean') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: String(result),
+        },
+      ],
+    };
+  }
+
+  // Handle object (including arrays)
+  if (typeof result === 'object') {
+    try {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch {
+      // JSON.stringify failed
+      return {
+        content: [
+          {
+            type: 'text',
+            text: String(result),
+          },
+        ],
+      };
+    }
+  }
+
+  // Fallback: convert to string
+  return {
+    content: [
+      {
+        type: 'text',
+        text: String(result),
+      },
+    ],
+  };
+}
+
+export function formatToolError(error: Error | string): ToolResult {
+  const message = error instanceof Error ? error.message : error;
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: message,
+      },
+    ],
+    isError: true,
+  };
+}
+
+export function formatTextResult(text: string): ToolResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text,
+      },
+    ],
+  };
+}
+
+export function formatJsonResult(data: unknown): ToolResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+export function mergeToolResults(results: ToolResult[]): ToolResult {
+  const mergedContent: McpContentBlock[] = [];
+  let hasError = false;
+
+  for (const result of results) {
+    mergedContent.push(...result.content);
+    if (result.isError) {
+      hasError = true;
+    }
+  }
+
+  return {
+    content: mergedContent,
+    isError: hasError,
+  };
+}
+
+export function isValidContentBlock(block: unknown): block is McpContentBlock {
+  if (!block || typeof block !== 'object') {
+    return false;
+  }
+
+  const blockObj = block as Record<string, unknown>;
+
+  if (!blockObj.type || typeof blockObj.type !== 'string') {
+    return false;
+  }
+
+  switch (blockObj.type) {
+    case 'text':
+      return typeof blockObj.text === 'string';
+
+    case 'image':
+      return (
+        typeof blockObj.data === 'string' &&
+        typeof blockObj.mimeType === 'string'
+      );
+
+    case 'resource':
+      return typeof blockObj.uri === 'string';
+
+    default:
+      return false;
+  }
+}

packages/sdk-typescript/src/mcp/tool.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool definition helper for SDK-embedded MCP servers
+ *
+ * Provides type-safe tool definitions with generic input/output types.
+ */
+
+import type { ToolDefinition } from '../types/types.js';
+
+export function tool<TInput = unknown, TOutput = unknown>(
+  def: ToolDefinition<TInput, TOutput>,
+): ToolDefinition<TInput, TOutput> {
+  // Validate tool definition
+  if (!def.name || typeof def.name !== 'string') {
+    throw new Error('Tool definition must have a name (string)');
+  }
+
+  if (!def.description || typeof def.description !== 'string') {
+    throw new Error(
+      `Tool definition for '${def.name}' must have a description (string)`,
+    );
+  }
+
+  if (!def.inputSchema || typeof def.inputSchema !== 'object') {
+    throw new Error(
+      `Tool definition for '${def.name}' must have an inputSchema (object)`,
+    );
+  }
+
+  if (!def.handler || typeof def.handler !== 'function') {
+    throw new Error(
+      `Tool definition for '${def.name}' must have a handler (function)`,
+    );
+  }
+
+  // Return definition (pass-through for type safety)
+  return def;
+}
+
+export function validateToolName(name: string): void {
+  if (!name) {
+    throw new Error('Tool name cannot be empty');
+  }
+
+  if (name.length > 64) {
+    throw new Error(
+      `Tool name '${name}' is too long (max 64 characters): ${name.length}`,
+    );
+  }
+
+  if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name)) {
+    throw new Error(
+      `Tool name '${name}' is invalid. Must start with a letter and contain only letters, numbers, and underscores.`,
+    );
+  }
+}
+
+export function validateInputSchema(schema: unknown): void {
+  if (!schema || typeof schema !== 'object') {
+    throw new Error('Input schema must be an object');
+  }
+
+  const schemaObj = schema as Record<string, unknown>;
+
+  if (!schemaObj.type) {
+    throw new Error('Input schema must have a type field');
+  }
+
+  // For object schemas, validate properties
+  if (schemaObj.type === 'object') {
+    if (schemaObj.properties && typeof schemaObj.properties !== 'object') {
+      throw new Error('Input schema properties must be an object');
+    }
+
+    if (schemaObj.required && !Array.isArray(schemaObj.required)) {
+      throw new Error('Input schema required must be an array');
+    }
+  }
+}
+
+export function createTool<TInput = unknown, TOutput = unknown>(
+  def: ToolDefinition<TInput, TOutput>,
+): ToolDefinition<TInput, TOutput> {
+  // Validate via tool() function
+  const validated = tool(def);
+
+  // Additional validation
+  validateToolName(validated.name);
+  validateInputSchema(validated.inputSchema);
+
+  return validated;
+}

packages/sdk-typescript/src/query/Query.ts

@@ -0,0 +1,698 @@
+/**
+ * Query class - Main orchestrator for SDK
+ *
+ * Manages SDK workflow, routes messages, and handles lifecycle.
+ * Implements AsyncIterator protocol for message consumption.
+ */
+
+const PERMISSION_CALLBACK_TIMEOUT = 30000;
+const MCP_REQUEST_TIMEOUT = 30000;
+const CONTROL_REQUEST_TIMEOUT = 30000;
+const STREAM_CLOSE_TIMEOUT = 10000;
+
+import { randomUUID } from 'node:crypto';
+import { SdkLogger } from '../utils/logger.js';
+import type {
+  SDKMessage,
+  SDKUserMessage,
+  CLIControlRequest,
+  CLIControlResponse,
+  ControlCancelRequest,
+  PermissionSuggestion,
+} from '../types/protocol.js';
+import {
+  isSDKUserMessage,
+  isSDKAssistantMessage,
+  isSDKSystemMessage,
+  isSDKResultMessage,
+  isSDKPartialAssistantMessage,
+  isControlRequest,
+  isControlResponse,
+  isControlCancel,
+} from '../types/protocol.js';
+import type { Transport } from '../transport/Transport.js';
+import type { QueryOptions } from '../types/types.js';
+import { Stream } from '../utils/Stream.js';
+import { serializeJsonLine } from '../utils/jsonLines.js';
+import { AbortError } from '../types/errors.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { SdkControlServerTransport } from '../mcp/SdkControlServerTransport.js';
+import { ControlRequestType } from '../types/protocol.js';
+
+interface PendingControlRequest {
+  resolve: (response: Record<string, unknown> | null) => void;
+  reject: (error: Error) => void;
+  timeout: NodeJS.Timeout;
+  abortController: AbortController;
+}
+
+interface TransportWithEndInput extends Transport {
+  endInput(): void;
+}
+
+const logger = SdkLogger.createLogger('Query');
+
+export class Query implements AsyncIterable<SDKMessage> {
+  private transport: Transport;
+  private options: QueryOptions;
+  private sessionId: string;
+  private inputStream: Stream<SDKMessage>;
+  private sdkMessages: AsyncGenerator<SDKMessage>;
+  private abortController: AbortController;
+  private pendingControlRequests: Map<string, PendingControlRequest> =
+    new Map();
+  private sdkMcpTransports: Map<string, SdkControlServerTransport> = new Map();
+  readonly initialized: Promise<void>;
+  private closed = false;
+  private messageRouterStarted = false;
+
+  private firstResultReceivedPromise?: Promise<void>;
+  private firstResultReceivedResolve?: () => void;
+
+  private readonly isSingleTurn: boolean;
+
+  constructor(
+    transport: Transport,
+    options: QueryOptions,
+    singleTurn: boolean = false,
+  ) {
+    this.transport = transport;
+    this.options = options;
+    this.sessionId = randomUUID();
+    this.inputStream = new Stream<SDKMessage>();
+    this.abortController = options.abortController ?? new AbortController();
+    this.isSingleTurn = singleTurn;
+
+    /**
+     * Create async generator proxy to ensure stream.next() is called at least once.
+     * The generator will start iterating when the user begins iteration.
+     * This ensures readResolve/readReject are set up as soon as iteration starts.
+     * If errors occur before iteration starts, they'll be stored in hasError and
+     * properly rejected when the user starts iterating.
+     */
+    this.sdkMessages = this.readSdkMessages();
+
+    this.firstResultReceivedPromise = new Promise((resolve) => {
+      this.firstResultReceivedResolve = resolve;
+    });
+
+    /**
+     * Handle abort signal if controller is provided and already aborted or will be aborted.
+     * If already aborted, set error immediately. Otherwise, listen for abort events
+     * and set abort error on the stream before closing.
+     */
+    if (this.abortController.signal.aborted) {
+      this.inputStream.error(new AbortError('Query aborted by user'));
+      this.close().catch((err) => {
+        logger.error('Error during abort cleanup:', err);
+      });
+    } else {
+      this.abortController.signal.addEventListener('abort', () => {
+        this.inputStream.error(new AbortError('Query aborted by user'));
+        this.close().catch((err) => {
+          logger.error('Error during abort cleanup:', err);
+        });
+      });
+    }
+
+    this.initialized = this.initialize();
+    this.initialized.catch(() => {});
+
+    this.startMessageRouter();
+  }
+
+  private async initialize(): Promise<void> {
+    try {
+      logger.debug('Initializing Query');
+
+      const sdkMcpServerNames = Array.from(this.sdkMcpTransports.keys());
+
+      await this.sendControlRequest(ControlRequestType.INITIALIZE, {
+        hooks: null,
+        sdkMcpServers:
+          sdkMcpServerNames.length > 0 ? sdkMcpServerNames : undefined,
+        mcpServers: this.options.mcpServers,
+        agents: this.options.agents,
+      });
+      logger.info('Query initialized successfully');
+    } catch (error) {
+      logger.error('Initialization error:', error);
+      throw error;
+    }
+  }
+
+  private startMessageRouter(): void {
+    if (this.messageRouterStarted) {
+      return;
+    }
+
+    this.messageRouterStarted = true;
+
+    (async () => {
+      try {
+        for await (const message of this.transport.readMessages()) {
+          await this.routeMessage(message);
+
+          if (this.closed) {
+            break;
+          }
+        }
+
+        if (this.abortController.signal.aborted) {
+          this.inputStream.error(new AbortError('Query aborted'));
+        } else {
+          this.inputStream.done();
+        }
+      } catch (error) {
+        this.inputStream.error(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    })();
+  }
+
+  private async routeMessage(message: unknown): Promise<void> {
+    if (isControlRequest(message)) {
+      await this.handleControlRequest(message);
+      return;
+    }
+
+    if (isControlResponse(message)) {
+      this.handleControlResponse(message);
+      return;
+    }
+
+    if (isControlCancel(message)) {
+      this.handleControlCancelRequest(message);
+      return;
+    }
+
+    if (isSDKSystemMessage(message)) {
+      /**
+       * SystemMessage contains session info (cwd, tools, model, etc.)
+       * that should be passed to user.
+       */
+      this.inputStream.enqueue(message);
+      return;
+    }
+
+    if (isSDKResultMessage(message)) {
+      if (this.firstResultReceivedResolve) {
+        this.firstResultReceivedResolve();
+      }
+      /**
+       * In single-turn mode, automatically close input after receiving result
+       * to signal completion to the CLI.
+       */
+      if (this.isSingleTurn && 'endInput' in this.transport) {
+        (this.transport as TransportWithEndInput).endInput();
+      }
+      this.inputStream.enqueue(message);
+      return;
+    }
+
+    if (
+      isSDKAssistantMessage(message) ||
+      isSDKUserMessage(message) ||
+      isSDKPartialAssistantMessage(message)
+    ) {
+      this.inputStream.enqueue(message);
+      return;
+    }
+
+    logger.warn('Unknown message type:', message);
+    this.inputStream.enqueue(message as SDKMessage);
+  }
+
+  private async handleControlRequest(
+    request: CLIControlRequest,
+  ): Promise<void> {
+    const { request_id, request: payload } = request;
+
+    logger.debug(`Handling control request: ${payload.subtype}`);
+    const requestAbortController = new AbortController();
+
+    try {
+      let response: Record<string, unknown> | null = null;
+
+      switch (payload.subtype) {
+        case 'can_use_tool':
+          response = await this.handlePermissionRequest(
+            payload.tool_name,
+            payload.input as Record<string, unknown>,
+            payload.permission_suggestions,
+            requestAbortController.signal,
+          );
+          break;
+
+        case 'mcp_message':
+          response = await this.handleMcpMessage(
+            payload.server_name,
+            payload.message as unknown as JSONRPCMessage,
+          );
+          break;
+
+        default:
+          throw new Error(
+            `Unknown control request subtype: ${payload.subtype}`,
+          );
+      }
+
+      await this.sendControlResponse(request_id, true, response);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.error(`Control request error (${payload.subtype}):`, errorMessage);
+      await this.sendControlResponse(request_id, false, errorMessage);
+    }
+  }
+
+  private async handlePermissionRequest(
+    toolName: string,
+    toolInput: Record<string, unknown>,
+    permissionSuggestions: PermissionSuggestion[] | null,
+    signal: AbortSignal,
+  ): Promise<Record<string, unknown>> {
+    /* Default deny all wildcard tool requests */
+    if (!this.options.canUseTool) {
+      return { behavior: 'deny', message: 'Denied' };
+    }
+
+    try {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error('Permission callback timeout')),
+          PERMISSION_CALLBACK_TIMEOUT,
+        );
+      });
+
+      const result = await Promise.race([
+        Promise.resolve(
+          this.options.canUseTool(toolName, toolInput, {
+            signal,
+            suggestions: permissionSuggestions,
+          }),
+        ),
+        timeoutPromise,
+      ]);
+
+      if (result.behavior === 'allow') {
+        return {
+          behavior: 'allow',
+          updatedInput: result.updatedInput ?? toolInput,
+        };
+      } else {
+        return {
+          behavior: 'deny',
+          message: result.message ?? 'Denied',
+          ...(result.interrupt !== undefined
+            ? { interrupt: result.interrupt }
+            : {}),
+        };
+      }
+    } catch (error) {
+      /**
+       * Timeout or error → deny (fail-safe).
+       * This ensures that any issues with the permission callback
+       * result in a safe default of denying access.
+       */
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.warn(
+        'Permission callback error (denying by default):',
+        errorMessage,
+      );
+      return {
+        behavior: 'deny',
+        message: `Permission check failed: ${errorMessage}`,
+      };
+    }
+  }
+
+  private async handleMcpMessage(
+    serverName: string,
+    message: JSONRPCMessage,
+  ): Promise<Record<string, unknown>> {
+    const transport = this.sdkMcpTransports.get(serverName);
+    if (!transport) {
+      throw new Error(
+        `MCP server '${serverName}' not found in SDK-embedded servers`,
+      );
+    }
+
+    /**
+     * Check if this is a request (has method and id) or notification.
+     * Requests need to wait for a response, while notifications are just routed.
+     */
+    const isRequest =
+      'method' in message && 'id' in message && message.id !== null;
+
+    if (isRequest) {
+      const response = await this.handleMcpRequest(
+        serverName,
+        message,
+        transport,
+      );
+      return { mcp_response: response };
+    } else {
+      transport.handleMessage(message);
+      return { mcp_response: { jsonrpc: '2.0', result: {}, id: 0 } };
+    }
+  }
+
+  private handleMcpRequest(
+    _serverName: string,
+    message: JSONRPCMessage,
+    transport: SdkControlServerTransport,
+  ): Promise<JSONRPCMessage> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('MCP request timeout'));
+      }, MCP_REQUEST_TIMEOUT);
+
+      const messageId = 'id' in message ? message.id : null;
+
+      /**
+       * Hook into transport to capture response.
+       * Temporarily replace sendToQuery to intercept the response message
+       * matching this request's ID, then restore the original handler.
+       */
+      const originalSend = transport.sendToQuery;
+      transport.sendToQuery = async (responseMessage: JSONRPCMessage) => {
+        if ('id' in responseMessage && responseMessage.id === messageId) {
+          clearTimeout(timeout);
+          transport.sendToQuery = originalSend;
+          resolve(responseMessage);
+        }
+        return originalSend(responseMessage);
+      };
+
+      transport.handleMessage(message);
+    });
+  }
+
+  private handleControlResponse(response: CLIControlResponse): void {
+    const { response: payload } = response;
+    const request_id = payload.request_id;
+
+    const pending = this.pendingControlRequests.get(request_id);
+    if (!pending) {
+      logger.warn(
+        'Received response for unknown request:',
+        request_id,
+        JSON.stringify(payload),
+      );
+      return;
+    }
+
+    clearTimeout(pending.timeout);
+    this.pendingControlRequests.delete(request_id);
+
+    if (payload.subtype === 'success') {
+      logger.debug(
+        `Control response success for request: ${request_id}: ${JSON.stringify(payload.response)}`,
+      );
+      pending.resolve(payload.response as Record<string, unknown> | null);
+    } else {
+      /**
+       * Extract error message from error field.
+       * Error can be either a string or an object with a message property.
+       */
+      const errorMessage =
+        typeof payload.error === 'string'
+          ? payload.error
+          : (payload.error?.message ?? 'Unknown error');
+      logger.error(
+        `Control response error for request ${request_id}:`,
+        errorMessage,
+      );
+      pending.reject(new Error(errorMessage));
+    }
+  }
+
+  private handleControlCancelRequest(request: ControlCancelRequest): void {
+    const { request_id } = request;
+
+    if (!request_id) {
+      logger.warn('Received cancel request without request_id');
+      return;
+    }
+
+    const pending = this.pendingControlRequests.get(request_id);
+    if (pending) {
+      logger.debug(`Cancelling control request: ${request_id}`);
+      pending.abortController.abort();
+      clearTimeout(pending.timeout);
+      this.pendingControlRequests.delete(request_id);
+      pending.reject(new AbortError('Request cancelled'));
+    }
+  }
+
+  private async sendControlRequest(
+    subtype: string,
+    data: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown> | null> {
+    const requestId = randomUUID();
+
+    const request: CLIControlRequest = {
+      type: 'control_request',
+      request_id: requestId,
+      request: {
+        subtype: subtype as never,
+        ...data,
+      } as CLIControlRequest['request'],
+    };
+
+    const responsePromise = new Promise<Record<string, unknown> | null>(
+      (resolve, reject) => {
+        const abortController = new AbortController();
+        const timeout = setTimeout(() => {
+          this.pendingControlRequests.delete(requestId);
+          reject(new Error(`Control request timeout: ${subtype}`));
+        }, CONTROL_REQUEST_TIMEOUT);
+
+        this.pendingControlRequests.set(requestId, {
+          resolve,
+          reject,
+          timeout,
+          abortController,
+        });
+      },
+    );
+
+    this.transport.write(serializeJsonLine(request));
+    return responsePromise;
+  }
+
+  private async sendControlResponse(
+    requestId: string,
+    success: boolean,
+    responseOrError: Record<string, unknown> | null | string,
+  ): Promise<void> {
+    const response: CLIControlResponse = {
+      type: 'control_response',
+      response: success
+        ? {
+            subtype: 'success',
+            request_id: requestId,
+            response: responseOrError as Record<string, unknown> | null,
+          }
+        : {
+            subtype: 'error',
+            request_id: requestId,
+            error: responseOrError as string,
+          },
+    };
+
+    this.transport.write(serializeJsonLine(response));
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+
+    for (const pending of this.pendingControlRequests.values()) {
+      pending.abortController.abort();
+      clearTimeout(pending.timeout);
+    }
+    this.pendingControlRequests.clear();
+
+    await this.transport.close();
+
+    /**
+     * Complete input stream - check if aborted first.
+     * Only set error/done if stream doesn't already have an error state.
+     */
+    if (this.inputStream.hasError === undefined) {
+      if (this.abortController.signal.aborted) {
+        this.inputStream.error(new AbortError('Query aborted'));
+      } else {
+        this.inputStream.done();
+      }
+    }
+
+    for (const transport of this.sdkMcpTransports.values()) {
+      try {
+        await transport.close();
+      } catch (error) {
+        logger.error('Error closing MCP transport:', error);
+      }
+    }
+    this.sdkMcpTransports.clear();
+    logger.info('Query closed');
+  }
+
+  private async *readSdkMessages(): AsyncGenerator<SDKMessage> {
+    for await (const message of this.inputStream) {
+      yield message;
+    }
+  }
+
+  async next(...args: [] | [unknown]): Promise<IteratorResult<SDKMessage>> {
+    return this.sdkMessages.next(...args);
+  }
+
+  async return(value?: unknown): Promise<IteratorResult<SDKMessage>> {
+    return this.sdkMessages.return(value);
+  }
+
+  async throw(e?: unknown): Promise<IteratorResult<SDKMessage>> {
+    return this.sdkMessages.throw(e);
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<SDKMessage> {
+    return this.sdkMessages;
+  }
+
+  async streamInput(messages: AsyncIterable<SDKUserMessage>): Promise<void> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    try {
+      /**
+       * Wait for initialization to complete before sending messages.
+       * This prevents "write after end" errors when streamInput is called
+       * with an empty iterable before initialization finishes.
+       */
+      await this.initialized;
+
+      for await (const message of messages) {
+        if (this.abortController.signal.aborted) {
+          break;
+        }
+        this.transport.write(serializeJsonLine(message));
+      }
+
+      /**
+       * In multi-turn mode with MCP servers, wait for first result
+       * to ensure MCP servers have time to process before next input.
+       * This prevents race conditions where the next input arrives before
+       * MCP servers have finished processing the current request.
+       */
+      if (
+        !this.isSingleTurn &&
+        this.sdkMcpTransports.size > 0 &&
+        this.firstResultReceivedPromise
+      ) {
+        await Promise.race([
+          this.firstResultReceivedPromise,
+          new Promise<void>((resolve) => {
+            setTimeout(() => {
+              resolve();
+            }, STREAM_CLOSE_TIMEOUT);
+          }),
+        ]);
+      }
+
+      this.endInput();
+    } catch (error) {
+      if (this.abortController.signal.aborted) {
+        logger.info('Aborted during input streaming');
+        this.inputStream.error(
+          new AbortError('Query aborted during input streaming'),
+        );
+        return;
+      }
+      throw error;
+    }
+  }
+
+  endInput(): void {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    if (
+      'endInput' in this.transport &&
+      typeof this.transport.endInput === 'function'
+    ) {
+      (this.transport as TransportWithEndInput).endInput();
+    }
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    await this.sendControlRequest(ControlRequestType.INTERRUPT);
+  }
+
+  async setPermissionMode(mode: string): Promise<void> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    await this.sendControlRequest(ControlRequestType.SET_PERMISSION_MODE, {
+      mode,
+    });
+  }
+
+  async setModel(model: string): Promise<void> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    await this.sendControlRequest(ControlRequestType.SET_MODEL, { model });
+  }
+
+  /**
+   * Get list of control commands supported by the CLI
+   *
+   * @returns Promise resolving to list of supported command names
+   * @throws Error if query is closed
+   */
+  async supportedCommands(): Promise<Record<string, unknown> | null> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    return this.sendControlRequest(ControlRequestType.SUPPORTED_COMMANDS);
+  }
+
+  /**
+   * Get the status of MCP servers
+   *
+   * @returns Promise resolving to MCP server status information
+   * @throws Error if query is closed
+   */
+  async mcpServerStatus(): Promise<Record<string, unknown> | null> {
+    if (this.closed) {
+      throw new Error('Query is closed');
+    }
+
+    return this.sendControlRequest(ControlRequestType.MCP_SERVER_STATUS);
+  }
+
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  isClosed(): boolean {
+    return this.closed;
+  }
+}