@midscene/shared 1.9.1 → 1.9.2-beta-20260605084246.0

package/dist/lib/mcp/tool-generator.js

@@ -165,6 +165,34 @@ function normalizeActionArgs(args, paramSchema) {
         ];
     }));
 }
+function mergeLocateDefaults(locate, defaults) {
+    let merged;
+    for (const [key, value] of Object.entries(defaults))if (void 0 === locate[key]) {
+        if ('deepLocate' !== key || void 0 === locate.deepThink) {
+            merged = merged ?? {
+                ...locate
+            };
+            merged[key] = value;
+        }
+    }
+    return merged ?? locate;
+}
+function applyLocateDefaults(args, paramSchema, locateDefaults) {
+    if (!paramSchema || 0 === Object.keys(locateDefaults).length) return args;
+    const shape = getZodObjectShape(paramSchema);
+    if (!shape) return args;
+    return Object.fromEntries(Object.entries(args).map(([key, value])=>{
+        const fieldSchema = shape[key];
+        if (fieldSchema && (0, external_zod_schema_utils_js_namespaceObject.isMidsceneLocatorField)(fieldSchema) && isRecord(value)) return [
+            key,
+            mergeLocateDefaults(value, locateDefaults)
+        ];
+        return [
+            key,
+            value
+        ];
+    }));
+}
 function serializeArgsToDescription(args) {
     try {
         return Object.entries(args).map(([key, value])=>{
@@ -320,7 +348,7 @@ function mergeToolCliMetadata(base, extra) {
         options
     } : void 0;
 }
-function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (args)=>args, initArgSchema = {}, initArgCliMetadata) {
+function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (args)=>args, initArgSchema = {}, initArgCliMetadata, toolDefaults = {}) {
     return actionSpace.map((action)=>{
         const schema = {
             ...extractActionSchema(action.paramSchema, action.name),
@@ -334,7 +362,8 @@ function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (arg
             handler: async (args)=>{
                 try {
                     const agent = await getAgent(args);
-                    const normalizedArgs = normalizeActionArgs(sanitizeArgs(args), action.paramSchema);
+                    let normalizedArgs = normalizeActionArgs(sanitizeArgs(args), action.paramSchema);
+                    if (toolDefaults.locate) normalizedArgs = applyLocateDefaults(normalizedArgs, action.paramSchema, toolDefaults.locate);
                     let actionResult;
                     try {
                         actionResult = await executeAction(agent, action.name, normalizedArgs);
@@ -353,7 +382,7 @@ function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (arg
         };
     });
 }
-function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
+function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata, toolDefaults = {}) {
     return [
         {
             name: 'take_screenshot',
@@ -392,6 +421,8 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
             description: 'Execute a natural language action. The AI will plan and perform multi-step operations in a single invocation, useful for transient UI interactions (e.g., Spotlight, dropdown menus) that disappear between separate commands.',
             schema: {
                 prompt: external_zod_namespaceObject.z.string().describe('Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"'),
+                deepLocate: external_zod_namespaceObject.z.boolean().optional().describe('Use deep locate for every element this action targets. Improves precision for small or ambiguous targets at the cost of speed. Defaults to the server --deep-locate setting.'),
+                deepThink: external_zod_namespaceObject.z.boolean().optional().describe('Plan this action with deep thinking (richer context and sub-goal decomposition). Helps with complex multi-step instructions at the cost of speed. Defaults to the server --deep-think setting.'),
                 ...initArgSchema
             },
             cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
@@ -400,9 +431,13 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
                 try {
                     const agent = await getAgent(args);
                     if (!agent.aiAction) return createErrorResult('act is not supported by this agent');
-                    const result = await agent.aiAction(prompt, {
-                        deepThink: false
-                    });
+                    const actOptions = {
+                        deepThink: false,
+                        ...toolDefaults.act
+                    };
+                    if (void 0 !== args.deepLocate) actOptions.deepLocate = args.deepLocate;
+                    if (void 0 !== args.deepThink) actOptions.deepThink = args.deepThink;
+                    const result = await agent.aiAction(prompt, actOptions);
                     return await captureScreenshotResult(agent, 'act', result);
                 } catch (error) {
                     const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
@@ -416,12 +451,14 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
             description: 'Assert a natural language statement against the current page/screen.',
             schema: {
                 prompt: external_zod_namespaceObject.z.string().describe('Natural language assertion to verify, e.g. "there is a login button visible"'),
+                message: external_zod_namespaceObject.z.string().optional().describe('Custom error message to throw when the assertion fails, e.g. "the login button should be visible".'),
                 ...external_user_prompt_js_namespaceObject.promptInputExtraSchema,
                 ...initArgSchema
             },
             cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
             handler: async (args = {})=>{
                 const prompt = args.prompt;
+                const message = args.message;
                 try {
                     const agent = await getAgent(args);
                     if (!agent.aiAssert) return createErrorResult('assert is not supported by this agent');
@@ -431,7 +468,7 @@ function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
                         imageName: args.imageName,
                         convertHttpImage2Base64: args.convertHttpImage2Base64
                     });
-                    await agent.aiAssert(userPrompt);
+                    await agent.aiAssert(userPrompt, message);
                     return {
                         content: [
                             {

package/dist/types/mcp/base-server.d.ts

@@ -1,5 +1,6 @@
 import type { ParseArgsConfig } from 'node:util';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolDefaults } from './tool-defaults';
 import type { IMidsceneTools } from './types';
 export interface BaseMCPServerConfig {
     name: string;
@@ -25,13 +26,17 @@ export interface LaunchMCPServerResult {
     close: () => Promise<void>;
 }
 /**
- * CLI argument configuration for MCP servers
+ * CLI argument configuration for MCP servers. Behavior flags (e.g.
+ * `--deep-locate`) are generated from {@link TOOL_BEHAVIOR_FLAGS}, so adding a
+ * new flag there exposes it here automatically.
  */
 export declare const CLI_ARGS_CONFIG: ParseArgsConfig['options'];
 export interface CLIArgs {
     mode?: string;
     port?: string;
     host?: string;
+    /** Behavior flags such as `deep-locate` / `deep-think` (see TOOL_BEHAVIOR_FLAGS). */
+    [flag: string]: string | boolean | undefined;
 }
 /**
  * Launch an MCP server based on CLI arguments
@@ -47,7 +52,15 @@ export declare abstract class BaseMCPServer {
     protected toolsManager?: IMidsceneTools;
     protected config: BaseMCPServerConfig;
     protected providedToolsManager?: IMidsceneTools;
+    protected toolDefaults: ToolDefaults;
     constructor(config: BaseMCPServerConfig, toolsManager?: IMidsceneTools);
+    /**
+     * Set the default options injected into generated tool calls (e.g. forced
+     * deep locate / deep think). Must be called before `launch()` /
+     * `launchHttp()` so they are applied to the tools manager before its tools
+     * are generated. Merges with any previously set defaults.
+     */
+    setToolDefaults(toolDefaults: ToolDefaults): void;
     /**
      * Platform-specific: create tools manager instance
      * This is only called if no tools manager was provided in constructor

package/dist/types/mcp/base-tools.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 import { type CliReportSession } from './cli-report-session';
+import { type ToolDefaults } from './tool-defaults';
 import type { BaseAgent, BaseDevice, IMidsceneTools, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 /**
  * Declarative description of a platform's agent init args.
@@ -38,6 +39,13 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
     protected mcpServer?: McpServer;
     protected agent?: TAgent;
     protected toolDefinitions: ToolDefinition[];
+    /**
+     * Default options injected into every generated tool call (e.g. forced deep
+     * locate / deep think). Set from server/CLI behavior flags before
+     * `initTools()` so they are baked into the generated tool handlers.
+     * See https://github.com/web-infra-dev/midscene/issues/2446.
+     */
+    protected toolDefaults: ToolDefaults;
     /**
      * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
      * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
@@ -117,6 +125,12 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
      * Set agent for the tools manager
      */
     setAgent(agent: TAgent): void;
+    /**
+     * Set the default options injected into generated tool calls. Must be called
+     * before `initTools()` because the values are captured into the generated
+     * tool handlers. Merges with any previously set defaults.
+     */
+    setToolDefaults(toolDefaults: ToolDefaults): void;
     /**
      * Helper: Convert base64 screenshot to image content array
      */

package/dist/types/mcp/index.d.ts

@@ -1,5 +1,6 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './tool-defaults';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';

package/dist/types/mcp/tool-defaults.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Unified, declarative mechanism for "force a default option on every tool
+ * call" behaviors exposed by MCP servers and the device / Agent Skill CLIs.
+ *
+ * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
+ * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
+ * The tool generator, servers, tools managers and CLI parsing are all generic
+ * over {@link ToolDefaults} and never need to learn about individual flags.
+ *
+ * See https://github.com/web-infra-dev/midscene/issues/2446.
+ */
+/**
+ * Default options injected into generated tool calls. Each field is an
+ * injection point; an explicit per-call value always wins over these defaults.
+ */
+export interface ToolDefaults {
+    /**
+     * Merged into every locate field of action tools (`Tap`, `Input`, ...).
+     * e.g. `{ deepLocate: true }`.
+     */
+    locate?: Record<string, unknown>;
+    /**
+     * Merged into the `act` tool's `aiAction` options.
+     * e.g. `{ deepLocate: true, deepThink: true }`.
+     */
+    act?: Record<string, unknown>;
+}
+export interface ToolBehaviorFlag {
+    /** Kebab-case CLI flag name, e.g. `deep-locate` (exposed as `--deep-locate`). */
+    cli: string;
+    /** One-line description for help output. */
+    description: string;
+    /** Default-option bags this flag turns on when present. */
+    defaults: ToolDefaults;
+}
+/**
+ * The single source of truth for behavior flags. Add a row to support a new
+ * `--flag`; nothing else in the pipeline needs to change.
+ */
+export declare const TOOL_BEHAVIOR_FLAGS: readonly ToolBehaviorFlag[];
+/** Merge two {@link ToolDefaults}, with `b` taking precedence over `a`. */
+export declare function mergeToolDefaults(a: ToolDefaults, b: ToolDefaults): ToolDefaults;
+/**
+ * Resolve the active {@link ToolDefaults} from a predicate that says whether a
+ * given flag (by its `cli` name) is enabled.
+ */
+export declare function resolveToolDefaults(isEnabled: (cli: string) => boolean): ToolDefaults;
+/**
+ * Split argv into the resolved {@link ToolDefaults} and the remaining args.
+ *
+ * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
+ * in argv and are not tied to a specific sub-command. They are recognized by
+ * exact kebab-case match — the same surface the MCP `parseArgs` config exposes
+ * — and removed so a strict per-command parser never sees them. Every other
+ * token is returned untouched and in order for that per-command parser.
+ *
+ * This is the single place that knows how a behavior flag looks on the command
+ * line; both the device / Agent Skill CLI and the MCP launch path resolve their
+ * defaults from {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ */
+export declare function stripBehaviorFlags(argv: readonly string[]): {
+    rawArgs: string[];
+    toolDefaults: ToolDefaults;
+};

package/dist/types/mcp/tool-generator.d.ts

@@ -1,3 +1,4 @@
+import type { ToolDefaults } from './tool-defaults';
 import type { ActionSpaceItem, BaseAgent, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 import { composeUserPrompt } from './user-prompt';
 export { composeUserPrompt };
@@ -5,8 +6,8 @@ export { composeUserPrompt };
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
-export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, sanitizeArgs?: (args: Record<string, unknown>) => Record<string, unknown>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];
+export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, sanitizeArgs?: (args: Record<string, unknown>) => Record<string, unknown>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata, toolDefaults?: ToolDefaults): ToolDefinition[];
 /**
  * Generate common tools (screenshot, act)
  */
-export declare function generateCommonTools(getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];
+export declare function generateCommonTools(getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata, toolDefaults?: ToolDefaults): ToolDefinition[];

package/dist/types/mcp/types.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
+import type { ToolDefaults } from './tool-defaults';
 /**
  * Default timeout constants for app loading verification
  */
@@ -130,4 +131,5 @@ export interface IMidsceneTools {
     attachToServer(server: McpServer): void;
     initTools(): Promise<void>;
     destroy?(): Promise<void>;
+    setToolDefaults?(toolDefaults: ToolDefaults): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.9.1",
+  "version": "1.9.2-beta-20260605084246.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/cli-runner.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import dotenv from 'dotenv';
 import { getDebug } from '../logger';
 import type { BaseMidsceneTools } from '../mcp/base-tools';
+import { stripBehaviorFlags } from '../mcp/tool-defaults';
 import type {
   ToolDefinition,
   ToolResult,
@@ -135,8 +136,18 @@ export async function runToolsCLI(
   scriptName: string,
   options?: CLIRunnerOptions,
 ): Promise<void> {
-  const rawArgs = options?.argv ?? process.argv.slice(2);
-  debug('CLI invoked: %s %s', scriptName, rawArgs.join(' '));
+  const inputArgs = options?.argv ?? process.argv.slice(2);
+  debug('CLI invoked: %s %s', scriptName, inputArgs.join(' '));
+
+  // Global behavior flags (e.g. `--deep-locate` / `--deep-think`) apply
+  // regardless of which command runs. `stripBehaviorFlags` is the single place
+  // that knows how they look on the command line: it resolves their defaults
+  // and returns the remaining args so the per-command parser never sees them.
+  // See https://github.com/web-infra-dev/midscene/issues/2446.
+  const { rawArgs, toolDefaults } = stripBehaviorFlags(inputArgs);
+  if (Object.keys(toolDefaults).length > 0) {
+    tools.setToolDefaults?.(toolDefaults);
+  }
 
   // Load .env from cwd before any tool initialization
   const envFile = join(process.cwd(), '.env');

package/src/mcp/base-server.ts

@@ -10,6 +10,12 @@ import express, {
   type Response,
 } from 'express';
 import { getErrorMessage } from './error-formatter';
+import {
+  TOOL_BEHAVIOR_FLAGS,
+  type ToolDefaults,
+  mergeToolDefaults,
+  resolveToolDefaults,
+} from './tool-defaults';
 import type { IMidsceneTools } from './types';
 
 export interface BaseMCPServerConfig {
@@ -47,18 +53,25 @@ interface SessionData {
 }
 
 /**
- * CLI argument configuration for MCP servers
+ * CLI argument configuration for MCP servers. Behavior flags (e.g.
+ * `--deep-locate`) are generated from {@link TOOL_BEHAVIOR_FLAGS}, so adding a
+ * new flag there exposes it here automatically.
  */
 export const CLI_ARGS_CONFIG: ParseArgsConfig['options'] = {
   mode: { type: 'string', default: 'stdio' },
   port: { type: 'string', default: '3000' },
   host: { type: 'string', default: 'localhost' },
+  ...Object.fromEntries(
+    TOOL_BEHAVIOR_FLAGS.map((flag) => [flag.cli, { type: 'boolean' as const }]),
+  ),
 };
 
 export interface CLIArgs {
   mode?: string;
   port?: string;
   host?: string;
+  /** Behavior flags such as `deep-locate` / `deep-think` (see TOOL_BEHAVIOR_FLAGS). */
+  [flag: string]: string | boolean | undefined;
 }
 
 /**
@@ -69,6 +82,7 @@ export function launchMCPServer(
   server: BaseMCPServer,
   args: CLIArgs,
 ): Promise<LaunchMCPServerResult> {
+  server.setToolDefaults(resolveToolDefaults((cli) => args[cli] === true));
   if (args.mode === 'http') {
     return server.launchHttp({
       port: Number.parseInt(args.port || '3000', 10),
@@ -91,6 +105,7 @@ export abstract class BaseMCPServer {
   protected toolsManager?: IMidsceneTools;
   protected config: BaseMCPServerConfig;
   protected providedToolsManager?: IMidsceneTools;
+  protected toolDefaults: ToolDefaults = {};
 
   constructor(config: BaseMCPServerConfig, toolsManager?: IMidsceneTools) {
     this.config = config;
@@ -102,6 +117,16 @@ export abstract class BaseMCPServer {
     this.providedToolsManager = toolsManager;
   }
 
+  /**
+   * Set the default options injected into generated tool calls (e.g. forced
+   * deep locate / deep think). Must be called before `launch()` /
+   * `launchHttp()` so they are applied to the tools manager before its tools
+   * are generated. Merges with any previously set defaults.
+   */
+  public setToolDefaults(toolDefaults: ToolDefaults): void {
+    this.toolDefaults = mergeToolDefaults(this.toolDefaults, toolDefaults);
+  }
+
   /**
    * Platform-specific: create tools manager instance
    * This is only called if no tools manager was provided in constructor
@@ -117,6 +142,10 @@ export abstract class BaseMCPServer {
     // Use provided tools manager if available, otherwise create new one
     this.toolsManager = this.providedToolsManager || this.createToolsManager();
 
+    // Apply the tool defaults before tools are generated so they are baked
+    // into the generated tool handlers.
+    this.toolsManager.setToolDefaults?.(this.toolDefaults);
+
     try {
       await this.toolsManager.initTools();
     } catch (error: unknown) {

package/src/mcp/base-tools.ts

@@ -14,6 +14,7 @@ import {
   extractNamespacedArgs,
   sanitizeNamespacedArgs,
 } from './init-arg-utils';
+import { type ToolDefaults, mergeToolDefaults } from './tool-defaults';
 import {
   generateCommonTools,
   generateToolsFromActionSpace,
@@ -74,6 +75,14 @@ export abstract class BaseMidsceneTools<
   protected agent?: TAgent;
   protected toolDefinitions: ToolDefinition[] = [];
 
+  /**
+   * Default options injected into every generated tool call (e.g. forced deep
+   * locate / deep think). Set from server/CLI behavior flags before
+   * `initTools()` so they are baked into the generated tool handlers.
+   * See https://github.com/web-infra-dev/midscene/issues/2446.
+   */
+  protected toolDefaults: ToolDefaults = {};
+
   /**
    * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
    * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
@@ -289,6 +298,7 @@ export abstract class BaseMidsceneTools<
       (args = {}) => this.sanitizeToolArgs(args),
       this.getAgentInitArgSchema(),
       this.getAgentInitArgCliMetadata(),
+      this.toolDefaults,
     );
 
     // 4. Add common tools (screenshot, waitFor)
@@ -296,6 +306,7 @@ export abstract class BaseMidsceneTools<
       (args = {}) => this.ensureAgent(this.extractAgentInitParam(args)),
       this.getAgentInitArgSchema(),
       this.getAgentInitArgCliMetadata(),
+      this.toolDefaults,
     );
     this.toolDefinitions.push(...actionTools, ...commonTools);
 
@@ -345,6 +356,15 @@ export abstract class BaseMidsceneTools<
     this.agent = agent;
   }
 
+  /**
+   * Set the default options injected into generated tool calls. Must be called
+   * before `initTools()` because the values are captured into the generated
+   * tool handlers. Merges with any previously set defaults.
+   */
+  public setToolDefaults(toolDefaults: ToolDefaults): void {
+    this.toolDefaults = mergeToolDefaults(this.toolDefaults, toolDefaults);
+  }
+
   /**
    * Helper: Convert base64 screenshot to image content array
    */

package/src/mcp/index.ts

@@ -1,5 +1,6 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './tool-defaults';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';

package/src/mcp/tool-defaults.ts

@@ -0,0 +1,120 @@
+/**
+ * Unified, declarative mechanism for "force a default option on every tool
+ * call" behaviors exposed by MCP servers and the device / Agent Skill CLIs.
+ *
+ * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
+ * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
+ * The tool generator, servers, tools managers and CLI parsing are all generic
+ * over {@link ToolDefaults} and never need to learn about individual flags.
+ *
+ * See https://github.com/web-infra-dev/midscene/issues/2446.
+ */
+
+/**
+ * Default options injected into generated tool calls. Each field is an
+ * injection point; an explicit per-call value always wins over these defaults.
+ */
+export interface ToolDefaults {
+  /**
+   * Merged into every locate field of action tools (`Tap`, `Input`, ...).
+   * e.g. `{ deepLocate: true }`.
+   */
+  locate?: Record<string, unknown>;
+  /**
+   * Merged into the `act` tool's `aiAction` options.
+   * e.g. `{ deepLocate: true, deepThink: true }`.
+   */
+  act?: Record<string, unknown>;
+}
+
+export interface ToolBehaviorFlag {
+  /** Kebab-case CLI flag name, e.g. `deep-locate` (exposed as `--deep-locate`). */
+  cli: string;
+  /** One-line description for help output. */
+  description: string;
+  /** Default-option bags this flag turns on when present. */
+  defaults: ToolDefaults;
+}
+
+/**
+ * The single source of truth for behavior flags. Add a row to support a new
+ * `--flag`; nothing else in the pipeline needs to change.
+ */
+export const TOOL_BEHAVIOR_FLAGS: readonly ToolBehaviorFlag[] = [
+  {
+    cli: 'deep-locate',
+    description:
+      'Force deep locate for every locating operation (better precision for small/ambiguous targets, a bit slower).',
+    defaults: { locate: { deepLocate: true }, act: { deepLocate: true } },
+  },
+  {
+    cli: 'deep-think',
+    description:
+      'Plan the act tool with deep thinking (richer context and sub-goal decomposition, a bit slower).',
+    defaults: { act: { deepThink: true } },
+  },
+];
+
+/** Merge two {@link ToolDefaults}, with `b` taking precedence over `a`. */
+export function mergeToolDefaults(
+  a: ToolDefaults,
+  b: ToolDefaults,
+): ToolDefaults {
+  const locate = { ...a.locate, ...b.locate };
+  const act = { ...a.act, ...b.act };
+  const result: ToolDefaults = {};
+  if (Object.keys(locate).length > 0) {
+    result.locate = locate;
+  }
+  if (Object.keys(act).length > 0) {
+    result.act = act;
+  }
+  return result;
+}
+
+/**
+ * Resolve the active {@link ToolDefaults} from a predicate that says whether a
+ * given flag (by its `cli` name) is enabled.
+ */
+export function resolveToolDefaults(
+  isEnabled: (cli: string) => boolean,
+): ToolDefaults {
+  return TOOL_BEHAVIOR_FLAGS.reduce<ToolDefaults>(
+    (acc, flag) =>
+      isEnabled(flag.cli) ? mergeToolDefaults(acc, flag.defaults) : acc,
+    {},
+  );
+}
+
+/**
+ * Split argv into the resolved {@link ToolDefaults} and the remaining args.
+ *
+ * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
+ * in argv and are not tied to a specific sub-command. They are recognized by
+ * exact kebab-case match — the same surface the MCP `parseArgs` config exposes
+ * — and removed so a strict per-command parser never sees them. Every other
+ * token is returned untouched and in order for that per-command parser.
+ *
+ * This is the single place that knows how a behavior flag looks on the command
+ * line; both the device / Agent Skill CLI and the MCP launch path resolve their
+ * defaults from {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ */
+export function stripBehaviorFlags(argv: readonly string[]): {
+  rawArgs: string[];
+  toolDefaults: ToolDefaults;
+} {
+  const enabled = new Set<string>();
+  const rawArgs: string[] = [];
+  for (const arg of argv) {
+    const flag = TOOL_BEHAVIOR_FLAGS.find((f) => arg === `--${f.cli}`);
+    if (flag) {
+      enabled.add(flag.cli);
+    } else {
+      rawArgs.push(arg);
+    }
+  }
+  return {
+    rawArgs,
+    toolDefaults: resolveToolDefaults((cli) => enabled.has(cli)),
+  };
+}