feat(tools): add ToolSearch for on-demand loading of deferred tool schemas

packages/cli/src/config/config.ts

@@ -31,6 +31,7 @@ import {
   isBareMode,
   isToolEnabled,
   type MCPServerConfig,
+  SchemaValidator,
 } from '@qwen-code/qwen-code-core';
 import { extensionsCommand } from '../commands/extensions.js';
 import { hooksCommand } from '../commands/hooks.js';
@@ -164,9 +165,75 @@ export interface CliArgs {
   channel: string | undefined;
   jsonFd?: number | undefined;
   jsonFile?: string | undefined;
+  jsonSchema?: string | undefined;
   inputFile?: string | undefined;
 }
 
+/**
+ * Resolves the `--json-schema` argument into a parsed JSON Schema object.
+ *
+ * Accepts either a JSON literal or `@path/to/schema.json`. Fails fast with a
+ * FatalConfigError if the input can't be read/parsed/compiled — invalid
+ * schemas should not silently skip validation at runtime.
+ */
+export function resolveJsonSchemaArg(
+  raw: string | undefined,
+): Record<string, unknown> | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new FatalConfigError('--json-schema cannot be empty.');
+  }
+
+  let payload: string;
+  if (trimmed.startsWith('@')) {
+    const resolvedPath = resolvePath(trimmed.slice(1));
+    try {
+      payload = fs.readFileSync(resolvedPath, 'utf8');
+    } catch (err) {
+      throw new FatalConfigError(
+        `--json-schema could not read "${resolvedPath}": ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  } else {
+    payload = trimmed;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch (err) {
+    throw new FatalConfigError(
+      `--json-schema is not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new FatalConfigError(
+      '--json-schema must be a JSON object describing a schema.',
+    );
+  }
+
+  // Ajv compile-time validation. SchemaValidator.validate is deliberately
+  // lenient at runtime (falls back to no-op on compile failure to support
+  // exotic MCP schemas) — but `--json-schema` is explicit user intent, so
+  // surface a bad schema here rather than letting it silently no-op later.
+  const compileError = SchemaValidator.compileStrict(parsed);
+  if (compileError) {
+    throw new FatalConfigError(
+      `--json-schema is not a valid JSON Schema: ${compileError}`,
+    );
+  }
+
+  return parsed as Record<string, unknown>;
+}
+
 function normalizeOutputFormat(
   format: string | OutputFormat | undefined,
 ): OutputFormat | undefined {
@@ -470,6 +537,14 @@ export async function parseArguments(): Promise<CliArgs> {
             'File path for structured JSON event output (dual output mode). ' +
             'Can be a regular file, FIFO (named pipe), or /dev/fd/N.',
         })
+        .option('json-schema', {
+          type: 'string',
+          description:
+            'JSON Schema that the model\'s final output must conform to ' +
+            '(headless mode only). Accepts a JSON literal or "@path/to/schema.json". ' +
+            'Registers a synthetic `structured_output` tool; the session ends on ' +
+            'the first valid call.',
+        })
         .option('input-file', {
           type: 'string',
           description:
@@ -603,6 +678,19 @@ export async function parseArguments(): Promise<CliArgs> {
           if (argv['jsonFd'] != null && argv['jsonFile'] != null) {
             return '--json-fd and --json-file are mutually exclusive. Use one or the other.';
           }
+          if (argv['jsonSchema']) {
+            if (argv['promptInteractive']) {
+              return '--json-schema cannot be used with --prompt-interactive (-i); structured output only terminates the non-interactive flow.';
+            }
+            const hasPrompt = !!argv['prompt'];
+            const query = argv['query'] as string | string[] | undefined;
+            const hasPositionalQuery = Array.isArray(query)
+              ? query.length > 0
+              : !!query;
+            if (!hasPrompt && !hasPositionalQuery) {
+              return '--json-schema only applies to non-interactive mode; pass a prompt via -p or as a positional argument.';
+            }
+          }
           return true;
         }),
     )
@@ -1316,6 +1404,7 @@ export async function loadCliConfig(
     // absent.
     jsonFd: argv.jsonFd,
     jsonFile: argv.jsonFile ?? settings.dualOutput?.jsonFile,
+    jsonSchema: resolveJsonSchemaArg(argv.jsonSchema),
     inputFile: argv.inputFile ?? settings.dualOutput?.inputFile,
     // Precedence: explicit CLI flag > settings file > default(true).
     // NOTE: do NOT set a yargs default for `chat-recording`, otherwise argv will

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

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveJsonSchemaArg } from './config.js';
+
+describe('resolveJsonSchemaArg', () => {
+  it('returns undefined when the arg is absent', () => {
+    expect(resolveJsonSchemaArg(undefined)).toBeUndefined();
+  });
+
+  it('parses an inline JSON literal into a schema object', () => {
+    const schema = resolveJsonSchemaArg(
+      '{"type":"object","properties":{"summary":{"type":"string"}}}',
+    );
+    expect(schema).toEqual({
+      type: 'object',
+      properties: { summary: { type: 'string' } },
+    });
+  });
+
+  it('reads schema from disk via @path syntax', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'qwen-schema-'));
+    const file = path.join(tmp, 'schema.json');
+    fs.writeFileSync(file, '{"type":"object"}');
+    try {
+      const schema = resolveJsonSchemaArg(`@${file}`);
+      expect(schema).toEqual({ type: 'object' });
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it('throws on empty string', () => {
+    expect(() => resolveJsonSchemaArg('   ')).toThrow(/cannot be empty/);
+  });
+
+  it('throws on invalid JSON', () => {
+    expect(() => resolveJsonSchemaArg('{not json}')).toThrow(
+      /not valid JSON/,
+    );
+  });
+
+  it('throws when the parsed value is not an object', () => {
+    expect(() => resolveJsonSchemaArg('[]')).toThrow(/must be a JSON object/);
+    expect(() => resolveJsonSchemaArg('"just a string"')).toThrow(
+      /must be a JSON object/,
+    );
+  });
+
+  it('throws when the referenced file does not exist', () => {
+    expect(() =>
+      resolveJsonSchemaArg('@/this/path/does/not/exist.json'),
+    ).toThrow(/could not read/);
+  });
+
+  it('throws when schema is syntactically JSON but invalid as a JSON Schema', () => {
+    // `type` must be a string or array, not a number.
+    expect(() => resolveJsonSchemaArg('{"type": 42}')).toThrow(
+      /not a valid JSON Schema/,
+    );
+  });
+
+  it('accepts a minimal empty-object schema', () => {
+    // `{}` is a valid schema that accepts anything.
+    expect(resolveJsonSchemaArg('{}')).toEqual({});
+  });
+
+  it('accepts a draft-2020-12 schema', () => {
+    const schema = resolveJsonSchemaArg(
+      '{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object"}',
+    );
+    expect(schema).toBeDefined();
+  });
+});

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

@@ -1244,6 +1244,43 @@ describe('BaseJsonOutputAdapter', () => {
         expect(result.result).toBe('');
       }
     });
+
+    it('includes structured_result and JSON-stringifies result when structuredResult is provided', () => {
+      const payload = { summary: 'hi', score: 42 };
+      const options: ResultOptions = {
+        isError: false,
+        durationMs: 1000,
+        apiDurationMs: 800,
+        numTurns: 1,
+        structuredResult: payload,
+      };
+
+      const result = adapter.exposeBuildResultMessage(options);
+
+      if (!result.is_error) {
+        expect(result.result).toBe(JSON.stringify(payload));
+        expect(
+          (result as unknown as { structured_result?: unknown })
+            .structured_result,
+        ).toEqual(payload);
+      }
+    });
+
+    it('omits structured_result when structuredResult is undefined (back-compat)', () => {
+      const options: ResultOptions = {
+        isError: false,
+        durationMs: 1000,
+        apiDurationMs: 800,
+        numTurns: 1,
+      };
+
+      const result = adapter.exposeBuildResultMessage(options);
+
+      expect(
+        (result as unknown as { structured_result?: unknown })
+          .structured_result,
+      ).toBeUndefined();
+    });
   });
 
   describe('startSubagentAssistantMessage', () => {

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

@@ -66,6 +66,12 @@ export interface ResultOptions {
   readonly stats?: SessionMetrics;
   readonly summary?: string;
   readonly subtype?: string;
+  /**
+   * Payload that the model submitted via the synthetic `structured_output`
+   * tool. When set, `result` is forced to the JSON-stringified form and a
+   * top-level `structured_result` field is added to the result message.
+   */
+  readonly structuredResult?: unknown;
 }
 
 /**
@@ -1188,7 +1194,14 @@ export abstract class BaseJsonOutputAdapter {
         error: { message: errorMessage },
       };
     } else {
-      const success: CLIResultMessageSuccess & { stats?: SessionMetrics } = {
+      const hasStructured = options.structuredResult !== undefined;
+      const finalResult = hasStructured
+        ? JSON.stringify(options.structuredResult)
+        : resultText;
+      const success: CLIResultMessageSuccess & {
+        stats?: SessionMetrics;
+        structured_result?: unknown;
+      } = {
         type: 'result',
         subtype:
           (options.subtype as CLIResultMessageSuccess['subtype']) ?? 'success',
@@ -1198,14 +1211,17 @@ export abstract class BaseJsonOutputAdapter {
         duration_ms: options.durationMs,
         duration_api_ms: options.apiDurationMs,
         num_turns: options.numTurns,
-        result: resultText,
+        result: finalResult,
         usage,
         permission_denials: [...this.permissionDenials],
       };
 
       if (options.stats) {
         success.stats = options.stats;
       }
+      if (hasStructured) {
+        success.structured_result = options.structuredResult;
+      }
 
       return success;
     }

packages/cli/src/nonInteractiveCli.test.ts

@@ -179,6 +179,7 @@ describe('runNonInteractive', () => {
       getContentGeneratorConfig: vi.fn().mockReturnValue({}),
       getDebugMode: vi.fn().mockReturnValue(false),
       getOutputFormat: vi.fn().mockReturnValue('text'),
+      getJsonSchema: vi.fn().mockReturnValue(undefined),
       getFolderTrustFeature: vi.fn().mockReturnValue(false),
       getFolderTrust: vi.fn().mockReturnValue(false),
       getIncludePartialMessages: vi.fn().mockReturnValue(false),