@swmansion/argent 0.22.2-next.0 → 0.22.2-next.10

package/dist/cli-cmds.mjs

@@ -2287,6 +2287,9 @@ var FAILURE_CODES = {
   SIMULATOR_SERVER_READY_TIMEOUT: "SIMULATOR_SERVER_READY_TIMEOUT",
   SIMULATOR_SERVER_PROCESS_ERROR: "SIMULATOR_SERVER_PROCESS_ERROR",
   SIMULATOR_SERVER_TERMINATED: "SIMULATOR_SERVER_TERMINATED",
+  SIMULATOR_COMMAND_REJECTED: "SIMULATOR_COMMAND_REJECTED",
+  SIMULATOR_COMMAND_ACK_TIMEOUT: "SIMULATOR_COMMAND_ACK_TIMEOUT",
+  SIMULATOR_COMMAND_TRANSPORT_FAILED: "SIMULATOR_COMMAND_TRANSPORT_FAILED",
   AX_QUERY_TIMEOUT: "AX_QUERY_TIMEOUT",
   AX_DAEMON_READY_TIMEOUT: "AX_DAEMON_READY_TIMEOUT",
   AX_DAEMON_EXITED_BEFORE_READY: "AX_DAEMON_EXITED_BEFORE_READY",
@@ -2815,6 +2818,10 @@ var FLAG_REGISTRY = [
     name: "disable-auto-screenshot",
     description: "Disable the automatic screenshot captured after interaction tools."
   },
+  {
+    name: "disable-auto-describe",
+    description: "Disable the accessibility element tree appended after interaction tools."
+  },
   {
     name: "argent-lens",
     description: "Argent Lens \u2014 the propose_variant / await_user_selection tools and the Electron preview window for staging UI design variants and letting a human pick among them. Off by default while the feature is in development."
@@ -3285,6 +3292,14 @@ var CONFIG_SCHEMA = [
     // drained/reset, not just the file rewritten.
     manageCommand: "argent telemetry"
   },
+  {
+    key: "allowlist.enabled",
+    description: "Whether `argent update` re-applies editor auto-approve allowlist rules. Unset (the default) keeps the current behavior: update refreshes the rules for editors that already have argent configured. Set to `false` to keep update from touching editor allowlists. `false` in either scope wins, so a committed project opt-out holds for every teammate.",
+    scopes: ["project", "global"],
+    parse: asBoolean,
+    merge: "prioritize-restrictive",
+    example: "false"
+  },
   {
     key: "lens.agent",
     description: "Coding-agent id remembered by `argent lens` to skip the picker.",
@@ -7210,7 +7225,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.22.2-next.0";
+    return "0.22.2-next.10";
   }
   return "0.0.0";
 }
@@ -7814,6 +7829,20 @@ function isScalarType(type) {
 function isJsonField(prop) {
   return prop?.type === "object" || prop?.type === "array" && !isScalarType(prop.items?.type);
 }
+function isRetiredField(prop) {
+  return prop.not !== void 0 && Object.keys(prop.not).length === 0;
+}
+function retirementGuidance(prop) {
+  return (prop.description ?? "").replace(/^Retired:\s*/, "");
+}
+function retiredFieldFor(flag, properties) {
+  const bare = flag.endsWith("-json") ? flag.slice(0, -"-json".length) : flag;
+  for (const name of [flag, bare, bare.startsWith("no-") ? bare.slice(3) : bare]) {
+    const prop = properties[name];
+    if (prop !== void 0) return isRetiredField(prop) ? name : void 0;
+  }
+  return void 0;
+}
 function flagNameFor(name, prop) {
   return isJsonField(prop) ? `--${name}-json` : `--${name}`;
 }
@@ -7893,6 +7922,13 @@ function parseFlags(argv, schema) {
     } else {
       flag = tok.slice(2);
     }
+    const retiredField = retiredFieldFor(flag, properties);
+    if (retiredField !== void 0) {
+      const guidance = retirementGuidance(properties[retiredField]);
+      throw new FlagParseException(
+        `--${retiredField} is retired${guidance ? `: ${guidance}` : ""}`
+      );
+    }
     if (flag === "args" && properties.args === void 0) {
       const { value: value2, nextIndex: nextIndex2 } = inlineValue !== void 0 ? { value: inlineValue, nextIndex: i2 } : takeNext(i2, "args");
       rawArgs = value2;
@@ -7984,19 +8020,25 @@ function formatSchemaUsage(schema) {
   const lines = [];
   const entries = Object.entries(schema.properties);
   if (entries.length === 0) return "  (no parameters)";
+  const live = entries.filter(([, prop]) => !isRetiredField(prop));
   let maxFlagLen = 0;
-  for (const [name, prop] of entries) {
+  for (const [name, prop] of live) {
     const display = renderFlagName(name, prop);
     if (display.length > maxFlagLen) maxFlagLen = display.length;
   }
-  for (const [name, prop] of entries) {
+  for (const [name, prop] of live) {
     const flag = renderFlagName(name, prop).padEnd(maxFlagLen, " ");
     const typeLabel = renderType(prop);
     const req = required.has(name) ? " (required)" : "";
     const desc = prop.description ? `  ${prop.description}` : "";
     lines.push(`  ${flag}  ${typeLabel}${req}${desc}`);
   }
-  if (entries.some(([, prop]) => prop.type === "boolean")) {
+  for (const [name, prop] of entries) {
+    if (!isRetiredField(prop)) continue;
+    const desc = retirementGuidance(prop);
+    lines.push(`  Retired: ${name}${desc ? ` - ${desc}` : ""}`);
+  }
+  if (live.some(([, prop]) => prop.type === "boolean")) {
     lines.push(
       "",
       "  Booleans: --flag, --flag true, or --flag 1 sets true; --flag false, --flag 0, --flag=false, or --no-flag sets false."
@@ -8024,9 +8066,12 @@ function renderType(prop) {
 
 // ../argent-cli/src/run-validation.ts
 function findMissingRequired(payload, schema) {
-  const required = new Set(schema?.required ?? []);
+  const properties = schema?.properties ?? {};
+  const required = new Set(
+    (schema?.required ?? []).filter((name) => !isRetiredField(properties[name] ?? {}))
+  );
   if (required.size === 0) return [];
-  const declared = Object.keys(schema?.properties ?? {});
+  const declared = Object.keys(properties);
   const names = [...declared.filter((n2) => required.has(n2))];
   for (const name of required) {
     if (!names.includes(name)) names.push(name);
@@ -8055,7 +8100,9 @@ function describeServerValidationFailure(err, payload, schema) {
   const properties = schema?.properties ?? {};
   const addressesThisTool = (issue) => issue.path.length === 0 || typeof issue.path[0] === "string" && Object.hasOwn(properties, issue.path[0]);
   if (!parsed.every(addressesThisTool)) return null;
-  const required = new Set(schema?.required ?? []);
+  const required = new Set(
+    (schema?.required ?? []).filter((name) => !isRetiredField(properties[name] ?? {}))
+  );
   const missing = [];
   const invalid = [];
   for (const issue of parsed) {
@@ -8259,15 +8306,14 @@ Examples:
     process.exit(1);
   }
   const schema = meta.inputSchema;
-  const failValidation = async (report, stage) => {
-    const summary = formatValidationError(report, schema);
+  const failInvocation = async (summary, report, failure) => {
     if (json) {
       console.error(
         JSON.stringify(
           {
             error: summary,
-            missing: missingFlagNames(report, schema),
-            issues: report.rawIssues ?? []
+            missing: report ? missingFlagNames(report, schema) : [],
+            issues: report?.rawIssues ?? []
           },
           null,
           2
@@ -8279,28 +8325,25 @@ Examples:
       printToolHelp(meta);
     }
     await trackRunFailure(toolName, startedAt, {
-      error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
-      failure_stage: stage,
+      ...failure,
       failure_area: "cli",
       error_kind: "validation"
     });
     process.exit(2);
   };
+  const failValidation = (report, stage) => failInvocation(formatValidationError(report, schema), report, {
+    error_code: FAILURE_CODES.CLI_RUN_INPUT_VALIDATION_FAILED,
+    failure_stage: stage
+  });
   let parsed;
   try {
     parsed = parseFlags(argvForFlags, schema);
   } catch (err) {
     if (err instanceof FlagParseException) {
-      console.error(`Error: ${err.message}
-`);
-      printToolHelp(meta);
-      await trackRunFailure(toolName, startedAt, {
+      await failInvocation(err.message, null, {
         error_code: FAILURE_CODES.CLI_RUN_FLAG_PARSE_FAILED,
-        failure_stage: "cli_run_parse_flags",
-        failure_area: "cli",
-        error_kind: "validation"
+        failure_stage: "cli_run_parse_flags"
       });
-      process.exit(2);
     }
     throw err;
   }

package/dist/installer.mjs

@@ -15095,6 +15095,31 @@ function readConfigObject(scope = "global", options = {}) {
   }
   return {};
 }
+var FORBIDDEN_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function splitKey(dottedKey) {
+  const parts = dottedKey.split(".");
+  if (parts.length === 0 || parts.some((p) => p === "")) {
+    throw new Error(`Invalid config key "${dottedKey}": empty path segment`);
+  }
+  for (const p of parts) {
+    if (FORBIDDEN_SEGMENTS.has(p)) {
+      throw new Error(`Invalid config key "${dottedKey}": forbidden segment "${p}"`);
+    }
+  }
+  return parts;
+}
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getAtPath(obj, dottedKey) {
+  const parts = splitKey(dottedKey);
+  let cur = obj;
+  for (const part of parts) {
+    if (!isPlainObject(cur)) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
 var LOCK_STALE_MS = 1e4;
 var LOCK_MAX_WAIT_MS = 2e3;
 var LOCK_RETRY_MS = 25;
@@ -15172,8 +15197,162 @@ var import_dotenv = __toESM(require_main(), 1);
 import * as fs4 from "node:fs";
 import * as path5 from "node:path";
 
+// ../configuration-core/src/merge.ts
+function mergeRestrictive(local, global2) {
+  if (local === void 0) return global2;
+  if (global2 === void 0) return local;
+  if (typeof local === "boolean" && typeof global2 === "boolean") {
+    return local && global2;
+  }
+  if (typeof local === "number" && typeof global2 === "number") {
+    return Math.min(local, global2);
+  }
+  return local;
+}
+function toArray(value) {
+  return Array.isArray(value) ? value : null;
+}
+function mergeUnion(local, global2) {
+  const l2 = toArray(local);
+  const g = toArray(global2);
+  if (l2 === null && g === null) return local ?? global2;
+  const merged = [...g ?? [], ...l2 ?? []];
+  return Array.from(new Set(merged));
+}
+function mergeIntersection(local, global2) {
+  const l2 = toArray(local);
+  const g = toArray(global2);
+  if (l2 === null && g === null) return local ?? global2;
+  if (l2 === null) return global2;
+  if (g === null) return local;
+  const globalSet = new Set(g);
+  return l2.filter((item) => globalSet.has(item));
+}
+function applyMergePolicy(policy, local, global2) {
+  if (typeof policy === "function") return policy({ local, global: global2 });
+  switch (policy) {
+    case "prioritize-local":
+      return local ?? global2;
+    case "prioritize-global":
+      return global2 ?? local;
+    case "prioritize-restrictive":
+      return mergeRestrictive(local, global2);
+    case "union":
+      return mergeUnion(local, global2);
+    case "intersection":
+      return mergeIntersection(local, global2);
+    default: {
+      const _exhaustive = policy;
+      return _exhaustive;
+    }
+  }
+}
+
+// ../configuration-core/src/config-schema.ts
+function asBoolean(raw) {
+  return typeof raw === "boolean" ? raw : void 0;
+}
+function asString(raw) {
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function asStringArray(raw) {
+  if (!Array.isArray(raw)) return void 0;
+  const out = [];
+  for (const item of raw) {
+    if (typeof item === "string" && item.trim() !== "") out.push(item.trim());
+  }
+  return out;
+}
+var CONFIG_SCHEMA = [
+  {
+    key: "telemetry.enabled",
+    description: "Whether anonymous opt-out telemetry is enabled (on by default; environment opt-outs like DO_NOT_TRACK are not reflected here \u2014 `argent telemetry status` shows effective consent). `false` in either scope wins, so a committed project opt-out holds for every teammate.",
+    scopes: ["project", "global"],
+    parse: asBoolean,
+    merge: "prioritize-restrictive",
+    // Opt-out: consent.ts reads an unstored value as enabled, so the config
+    // surface must show the same rather than "(unset)".
+    default: true,
+    // Opt-in/out goes through the dedicated command so the live client is
+    // drained/reset, not just the file rewritten.
+    manageCommand: "argent telemetry"
+  },
+  {
+    key: "allowlist.enabled",
+    description: "Whether `argent update` re-applies editor auto-approve allowlist rules. Unset (the default) keeps the current behavior: update refreshes the rules for editors that already have argent configured. Set to `false` to keep update from touching editor allowlists. `false` in either scope wins, so a committed project opt-out holds for every teammate.",
+    scopes: ["project", "global"],
+    parse: asBoolean,
+    merge: "prioritize-restrictive",
+    example: "false"
+  },
+  {
+    key: "lens.agent",
+    description: "Coding-agent id remembered by `argent lens` to skip the picker.",
+    scopes: ["project", "global"],
+    parse: asString,
+    merge: "prioritize-local",
+    example: "claude"
+  },
+  {
+    key: "ios.additionalDeviceSets",
+    description: "Additional CoreSimulator device-set directories whose simulators argent should see alongside the default set. Absolute paths (or ~/\u2026); relative entries resolve against the project root (project scope) or home (global scope).",
+    scopes: ["project", "global"],
+    parse: asStringArray,
+    // Additive rather than shadowing: global baseline first, project extras
+    // after, deduplicated. `getAdditionalIosDeviceSets` re-implements this union
+    // (path resolution must precede dedup) and guards on the preset staying "union".
+    merge: "union",
+    example: '["~/DeviceSets/ci"]'
+  },
+  {
+    key: "recordings.directory",
+    description: "Directory where finished screen recordings (mp4) are saved on the client host. Absolute, `~`-prefixed, or relative to the project root (home dir when not in a project). Unset \u21D2 `.argent/recordings` under the project root.",
+    scopes: ["project", "global"],
+    parse: asString,
+    // Resolved on the client (the machine the mp4 is persisted to), so with a
+    // remote `argent link` tool-server it is the *client's* config that decides.
+    merge: "prioritize-local",
+    example: "~/Movies/argent"
+  }
+];
+function getConfigDefinition(key, registry = CONFIG_SCHEMA) {
+  return registry.find((def) => def.key === key);
+}
+
 // ../configuration-core/src/config-access.ts
 import * as path6 from "node:path";
+function readScopeValue(def, scope, options) {
+  if (!def.scopes.includes(scope)) return void 0;
+  const raw = getAtPath(readConfigObject(scope, options), def.key);
+  return raw === void 0 ? void 0 : def.parse(raw);
+}
+function getConfigValue(def, options = {}) {
+  const local = readScopeValue(def, "project", options);
+  const global2 = readScopeValue(def, "global", options);
+  const merged = applyMergePolicy(def.merge, local, global2);
+  return merged ?? def.default;
+}
+function getConfigValueByKey(key, options = {}, registry = CONFIG_SCHEMA) {
+  const def = requireDefinition(key, registry);
+  return getConfigValue(def, options);
+}
+function requireDefinition(key, registry = CONFIG_SCHEMA) {
+  const def = getConfigDefinition(key, registry);
+  if (!def) {
+    throw new UnknownConfigKeyError(key);
+  }
+  return def;
+}
+var UnknownConfigKeyError = class extends Error {
+  constructor(key) {
+    super(`Unknown configuration key "${key}".`);
+    this.key = key;
+    this.name = "UnknownConfigKeyError";
+  }
+  key;
+};
 
 // ../telemetry/src/paths.ts
 function identityFilePath() {
@@ -15443,6 +15622,9 @@ var FAILURE_CODES = {
   SIMULATOR_SERVER_READY_TIMEOUT: "SIMULATOR_SERVER_READY_TIMEOUT",
   SIMULATOR_SERVER_PROCESS_ERROR: "SIMULATOR_SERVER_PROCESS_ERROR",
   SIMULATOR_SERVER_TERMINATED: "SIMULATOR_SERVER_TERMINATED",
+  SIMULATOR_COMMAND_REJECTED: "SIMULATOR_COMMAND_REJECTED",
+  SIMULATOR_COMMAND_ACK_TIMEOUT: "SIMULATOR_COMMAND_ACK_TIMEOUT",
+  SIMULATOR_COMMAND_TRANSPORT_FAILED: "SIMULATOR_COMMAND_TRANSPORT_FAILED",
   AX_QUERY_TIMEOUT: "AX_QUERY_TIMEOUT",
   AX_DAEMON_READY_TIMEOUT: "AX_DAEMON_READY_TIMEOUT",
   AX_DAEMON_EXITED_BEFORE_READY: "AX_DAEMON_EXITED_BEFORE_READY",
@@ -16428,7 +16610,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.22.2-next.0";
+    return "0.22.2-next.10";
   }
   return "0.0.0";
 }
@@ -23369,12 +23551,15 @@ async function update(args) {
           )
         );
       }
-      for (const [scope, adapters] of adaptersByScope) {
-        for (const adapter of adapters) {
-          if (!adapter.addAllowlist) continue;
-          try {
-            adapter.addAllowlist(projectRoot, scope);
-          } catch {
+      const allowlistDisabled = getConfigValueByKey("allowlist.enabled", { cwd: projectRoot }) === false;
+      if (!allowlistDisabled) {
+        for (const [scope, adapters] of adaptersByScope) {
+          for (const adapter of adapters) {
+            if (!adapter.addAllowlist) continue;
+            try {
+              adapter.addAllowlist(projectRoot, scope);
+            } catch {
+            }
           }
         }
       }
@@ -23385,6 +23570,11 @@ async function update(args) {
         ...copyRulesAndAgents(localAdapters, projectRoot, "local", RULES_DIR, AGENTS_DIR)
       ];
       spinner2.stop("Configuration refreshed.");
+      if (allowlistDisabled) {
+        log.info(
+          import_picocolors11.default.dim("Left editor auto-approve allowlists alone (allowlist.enabled is false).")
+        );
+      }
       if (results.length > 0) {
         note(results.join("\n"), "MCP Configs Updated");
       }

package/dist/mcp-server.mjs

@@ -16471,6 +16471,9 @@ var FAILURE_CODES = {
   SIMULATOR_SERVER_READY_TIMEOUT: "SIMULATOR_SERVER_READY_TIMEOUT",
   SIMULATOR_SERVER_PROCESS_ERROR: "SIMULATOR_SERVER_PROCESS_ERROR",
   SIMULATOR_SERVER_TERMINATED: "SIMULATOR_SERVER_TERMINATED",
+  SIMULATOR_COMMAND_REJECTED: "SIMULATOR_COMMAND_REJECTED",
+  SIMULATOR_COMMAND_ACK_TIMEOUT: "SIMULATOR_COMMAND_ACK_TIMEOUT",
+  SIMULATOR_COMMAND_TRANSPORT_FAILED: "SIMULATOR_COMMAND_TRANSPORT_FAILED",
   AX_QUERY_TIMEOUT: "AX_QUERY_TIMEOUT",
   AX_DAEMON_READY_TIMEOUT: "AX_DAEMON_READY_TIMEOUT",
   AX_DAEMON_EXITED_BEFORE_READY: "AX_DAEMON_EXITED_BEFORE_READY",
@@ -17153,6 +17156,14 @@ var CONFIG_SCHEMA = [
     // drained/reset, not just the file rewritten.
     manageCommand: "argent telemetry"
   },
+  {
+    key: "allowlist.enabled",
+    description: "Whether `argent update` re-applies editor auto-approve allowlist rules. Unset (the default) keeps the current behavior: update refreshes the rules for editors that already have argent configured. Set to `false` to keep update from touching editor allowlists. `false` in either scope wins, so a committed project opt-out holds for every teammate.",
+    scopes: ["project", "global"],
+    parse: asBoolean,
+    merge: "prioritize-restrictive",
+    example: "false"
+  },
   {
     key: "lens.agent",
     description: "Coding-agent id remembered by `argent lens` to skip the picker.",
@@ -18491,7 +18502,7 @@ async function stepArtifactBlocks(artifacts, status, ctx, depth) {
   return blocks;
 }
 
-// ../argent-mcp/src/auto-screenshot.ts
+// ../argent-mcp/src/auto-capture.ts
 var AUTO_SCREENSHOT_TOOLS = /* @__PURE__ */ new Set([
   "gesture-tap",
   "gesture-swipe",
@@ -18532,6 +18543,30 @@ var DEFAULT_DELAY_MS = 1400;
 function autoScreenshotEnabled(options) {
   return !isFlagEnabled("disable-auto-screenshot", options);
 }
+var AUTO_DESCRIBE_TOOLS = /* @__PURE__ */ new Set([
+  "gesture-tap",
+  "gesture-swipe",
+  "gesture-scroll",
+  "gesture-drag",
+  "gesture-custom",
+  "gesture-pinch",
+  "gesture-rotate",
+  "button",
+  "keyboard",
+  "paste",
+  "rotate",
+  "launch-app",
+  "restart-app",
+  "open-url",
+  "run-sequence"
+]);
+function autoDescribeEnabled(options) {
+  return !isFlagEnabled("disable-auto-describe", options);
+}
+var AUTO_DESCRIBE_HEADER = "--- Elements after action (describe) ---";
+function shouldAutoDescribe(toolName) {
+  return AUTO_DESCRIBE_TOOLS.has(normalizeToolName(toolName));
+}
 var SECRET_PLACEHOLDER_MARKER = "{{secret:";
 function containsSecretPlaceholder(args) {
   try {
@@ -18628,6 +18663,7 @@ async function startMcpServer(options) {
     markFirstRunNoticeShown();
   }
   const autoScreenshotOn = autoScreenshotEnabled();
+  const autoDescribeOn = autoDescribeEnabled();
   let TOOLS_URL;
   let AUTH_TOKEN;
   const resolved = await getResolvedToolsUrl();
@@ -18715,7 +18751,7 @@ async function startMcpServer(options) {
     { name: "argent", version: getInstalledVersion() },
     {
       capabilities: { tools: {} },
-      instructions: "Argent \u2014 iOS Simulator, Android Emulator, and Chromium app control for interacting, testing, profiling and debugging mobile and Chromium applications. Always use discovery tools (describe / debugger-component-tree / screenshot) before tapping \u2014 never guess coordinates. On session end: call stop-all-simulator-servers with devices: [...] naming the devices this session used, and perform any necessary cleanup. One tool-server is shared by every agent using this argent install, so an unscoped call tears down their devices too \u2014 reserve it for a deliberate machine-wide cleanup. Full guidance is in the argent rule loaded from .claude/rules/argent.md."
+      instructions: "Argent \u2014 iOS Simulator, Android Emulator, and Chromium app control for interacting, testing, profiling and debugging mobile and Chromium applications. Interaction tools return the screen after the action: a screenshot plus the accessibility element tree with normalized tap frames. Take coordinates from that tree; call describe (or debugger-component-tree) only when no fresh tree is available \u2014 never guess coordinates from pixels. On session end: call stop-all-simulator-servers with devices: [...] naming the devices this session used, and perform any necessary cleanup. One tool-server is shared by every agent using this argent install, so an unscoped call tears down their devices too \u2014 reserve it for a deliberate machine-wide cleanup. Full guidance is in the argent rule loaded from .claude/rules/argent.md."
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -18767,15 +18803,17 @@ async function startMcpServer(options) {
         content = await toMcpContent(result, outputHint, ctx, params.arguments);
       }
       const udid = getUdidFromArgs(params.arguments);
-      if (autoScreenshotOn && udid && shouldAutoScreenshot(params.name) && containsSecretPlaceholder(params.arguments)) {
+      const wantScreenshot = autoScreenshotOn && shouldAutoScreenshot(params.name);
+      const wantTree = autoDescribeOn && shouldAutoDescribe(params.name);
+      if (udid && (wantScreenshot || wantTree) && containsSecretPlaceholder(params.arguments)) {
         content = [
           ...content,
           {
             type: "text",
-            text: "Auto-screenshot skipped: the input contains a {{secret:\u2026}} placeholder, and a screenshot of this screen could reveal the typed secret. The secret is already typed \u2014 do not send the typing step again, or the field will hold two copies of it. Submit or navigate away, then verify the resulting screen as usual. Only this call is covered: the next call is screenshotted normally, and captures the secret if the field is still on screen. To cover the submit as well, put the typing and the submit in ONE `run-sequence` the next time you type a secret."
+            text: "Auto-screenshot and element tree skipped: the input contains a {{secret:\u2026}} placeholder, and a capture of this screen could reveal the typed secret. The secret is already typed \u2014 do not send the typing step again, or the field will hold two copies of it. Submit or navigate away, then verify the resulting screen as usual. Only this call is covered: the next call is captured normally, and shows the secret if the field is still on screen. To cover the submit as well, put the typing and the submit in ONE `run-sequence` the next time you type a secret."
           }
         ];
-      } else if (autoScreenshotOn && udid && shouldAutoScreenshot(params.name)) {
+      } else if (udid && (wantScreenshot || wantTree)) {
         const maxWaitMs = getAutoScreenshotDelayMs(params.name);
         if (maxWaitMs > 0) {
           try {
@@ -18791,25 +18829,56 @@ async function startMcpServer(options) {
             await new Promise((r) => setTimeout(r, maxWaitMs));
           }
         }
-        try {
-          const screenshotResult = await callTool("screenshot", { udid });
-          const screenshotContent = await toMcpContent(screenshotResult.result, "image", {
-            toolsUrl: TOOLS_URL,
-            authToken: AUTH_TOKEN,
-            deviceId: udid
-          });
-          const hasImage = screenshotContent.some((b) => b.type === "image");
-          if (hasImage) {
-            content = [
-              ...content,
-              {
-                type: "text",
-                text: "--- Screen after action ---"
-              },
-              ...screenshotContent
-            ];
+        if (wantScreenshot) {
+          try {
+            const screenshotResult = await callTool("screenshot", { udid });
+            const screenshotContent = await toMcpContent(screenshotResult.result, "image", {
+              toolsUrl: TOOLS_URL,
+              authToken: AUTH_TOKEN,
+              deviceId: udid
+            });
+            const hasImage = screenshotContent.some((b) => b.type === "image");
+            if (hasImage) {
+              content = [
+                ...content,
+                {
+                  type: "text",
+                  text: "--- Screen after action ---"
+                },
+                ...screenshotContent
+              ];
+            }
+          } catch {
+          }
+        }
+        if (wantTree) {
+          const t1 = Date.now();
+          try {
+            const d = await callTool("describe", { udid });
+            const desc = d.result?.description;
+            if (typeof desc === "string" && desc.length > 0) {
+              content = [
+                ...content,
+                { type: "text", text: `${AUTO_DESCRIBE_HEADER}
+${desc}` }
+              ];
+            }
+            await spyLog({
+              ts: (/* @__PURE__ */ new Date()).toISOString(),
+              event: "auto_describe",
+              name: params.name,
+              durationMs: Date.now() - t1,
+              chars: typeof desc === "string" ? desc.length : 0
+            });
+          } catch (e) {
+            await spyLog({
+              ts: (/* @__PURE__ */ new Date()).toISOString(),
+              event: "auto_describe",
+              name: params.name,
+              durationMs: Date.now() - t1,
+              error: String(e instanceof Error ? e.message : e)
+            });
           }
-        } catch {
         }
       }
       if (note) {