deepline 0.3.324 → 0.3.326

package/dist/cli/{chunk-G4F2AIQ5.js → chunk-5NXHSRRE.js}

@@ -1,7 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
 
-var _chunkGROXVGGWjs = require('./chunk-GROXVGGW.js');
+var _chunkCUUHQ3AOjs = require('./chunk-CUUHQ3AO.js');
 
 // src/cli/commands/sessions.ts
 
@@ -420,7 +420,7 @@ function buildSessionUploadContent(raw) {
   return { encodedContent: encoded, needsChunking: true };
 }
 async function uploadPayload(path, payload) {
-  const { http } = _chunkGROXVGGWjs.getAuthedHttpClient.call(void 0, );
+  const { http } = _chunkCUUHQ3AOjs.getAuthedHttpClient.call(void 0, );
   return await http.post(path, payload);
 }
 async function uploadChunkedSessions(sessions, options) {
@@ -452,7 +452,7 @@ async function uploadChunkedSessions(sessions, options) {
     environments: sessions.map(() => detectShellContext()),
     ...options.rating ? { rating: options.rating } : {}
   });
-  _chunkGROXVGGWjs.printCommandEnvelope.call(void 0, 
+  _chunkCUUHQ3AOjs.printCommandEnvelope.call(void 0, 
     {
       ...response,
       ok: true,
@@ -481,7 +481,7 @@ async function handleSessionsSend(options) {
       filename: _path.basename.call(void 0, filePath),
       ...rating ? { rating } : {}
     });
-    _chunkGROXVGGWjs.printCommandEnvelope.call(void 0, 
+    _chunkCUUHQ3AOjs.printCommandEnvelope.call(void 0, 
       {
         ...response2,
         ok: true,
@@ -530,7 +530,7 @@ async function handleSessionsSend(options) {
     environment: detectShellContext(),
     ...rating ? { rating } : {}
   });
-  _chunkGROXVGGWjs.printCommandEnvelope.call(void 0, 
+  _chunkCUUHQ3AOjs.printCommandEnvelope.call(void 0, 
     {
       ...response,
       ok: true,
@@ -635,7 +635,7 @@ ${refreshMeta}
 </body>
 </html>`;
   _fs.writeFileSync.call(void 0, outputPath, html, "utf8");
-  _chunkGROXVGGWjs.printCommandEnvelope.call(void 0, 
+  _chunkCUUHQ3AOjs.printCommandEnvelope.call(void 0, 
     {
       ok: true,
       file: outputPath,

package/dist/cli/{chunk-XNL3SEMC.js → chunk-AFNEQ43J.js}

@@ -1,4 +1,8 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/cli/described.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+var _chunkAID3OYVJjs = require('./chunk-AID3OYVJ.js');
+
+// src/cli/described.ts
 var SHAPE = "{}";
 var SCHEMA_LINE_LIMIT = 100;
 function isRecord(value) {
@@ -288,9 +292,10 @@ function examples(described, options) {
   if (runner.via === "monitor") return { cli: runner.deploy, play: null };
   if (runner.via === "tool") {
     return {
-      cli: `deepline tools execute ${runner.toolId} --input '${input}'`,
+      cli: `deepline tools execute ${runner.toolId} --input ${_chunkAID3OYVJjs.shellQuote.call(void 0, input)}`,
       play: [
         "const result = await ctx.tools.execute({",
+        "  staleAfterSeconds: 0,",
         `  id: '${safeIdentifier(runner.toolId)}',`,
         `  tool: '${runner.toolId}',`,
         `  input: ${input},`,
@@ -300,7 +305,7 @@ function examples(described, options) {
     };
   }
   return {
-    cli: _nullishCoalesce(runner.cli, () => ( `deepline plays run ${runner.reference} --input '${input}'`)),
+    cli: _nullishCoalesce(runner.cli, () => ( `deepline plays run ${runner.reference} --input ${_chunkAID3OYVJjs.shellQuote.call(void 0, input)}`)),
     play: [
       `const output = await ctx.runPlay('${safeIdentifier(runner.reference.replace(/^.*\//, ""))}', '${runner.reference}', ${input});`,
       ...reads((field) => `output.${field.name}`)

package/dist/cli/{chunk-XSEMQ4II.js → chunk-AGH6YP2T.js}

@@ -3408,7 +3408,8 @@ async function bundlePlayFile2(filePath, options = {}) {
     exportName: options.exportName,
     adapter: {
       ...createSdkPlayBundlingAdapter(),
-      sourceIdentityRoot
+      sourceIdentityRoot,
+      ...options.cache === false ? { cacheDir: null } : {}
     }
   });
   if (result.success)

package/dist/cli/chunk-AID3OYVJ.js

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/cli/shell-quote.ts
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+
+
+exports.shellQuote = shellQuote;

package/dist/cli/{chunk-HHZDWBSQ.mjs → chunk-BQJVMKWL.mjs}

@@ -49,7 +49,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.324",
+  version: "0.3.326",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/{chunk-TJGJTB5T.mjs → chunk-BR7GGTAE.mjs}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-DLIRSHV6.mjs";
 import {
   SDK_RELEASE
-} from "./chunk-HHZDWBSQ.mjs";
+} from "./chunk-BQJVMKWL.mjs";
 import {
   DeeplineError,
   TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
@@ -17,6 +17,28 @@ import {
 } from "./chunk-NXGCO4JB.mjs";
 
 // src/errors.ts
+var CustomerDbQueryOutcomeUnknownError = class extends DeeplineError {
+  outcome = "unknown";
+  operationKey;
+  retryable;
+  constructor(cause, operationKey, options = {}) {
+    const recoveryAvailable = operationKey !== void 0 && options.recoveryAvailable !== false;
+    super(
+      operationKey === void 0 ? "SQL outcome is unknown. The unkeyed request was attempted once; inspect the database before issuing another write. An operation key added afterwards cannot recover this request." : recoveryAvailable ? "SQL outcome is unknown. Recover by submitting the same SQL and options with the original operation key; do not use a new key." : "SQL outcome is unknown. The server did not confirm atomic recovery support. Do not resubmit this write; inspect the database and confirm reader support before recovering with the original operation key.",
+      cause.statusCode,
+      "CUSTOMER_DB_QUERY_OUTCOME_UNKNOWN",
+      {
+        outcome: "unknown",
+        recovery: recoveryAvailable ? "original_operation_key" : "unavailable",
+        causeCode: cause.code
+      }
+    );
+    this.name = "CustomerDbQueryOutcomeUnknownError";
+    this.operationKey = operationKey;
+    this.retryable = recoveryAvailable;
+    Object.defineProperty(this, "cause", { value: cause, configurable: true });
+  }
+};
 var AuthError = class extends DeeplineError {
   /** Constructed by the SDK when Deepline rejects the caller's credentials. */
   constructor(message = "Authentication failed. Check your DEEPLINE_API_KEY.") {
@@ -1950,6 +1972,7 @@ ${COWORK_NETWORK_HINT}`;
 }
 
 export {
+  CustomerDbQueryOutcomeUnknownError,
   AuthError,
   RateLimitError,
   ToolRateLimitError,

package/dist/cli/{chunk-IXYR65PW.js → chunk-BUYZEUY4.js}

@@ -49,7 +49,7 @@ var SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: "0.3.324",
+  version: "0.3.326",
   updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/{chunk-GROXVGGW.js → chunk-CUUHQ3AO.js}

@@ -3,7 +3,7 @@
 
 
 
-var _chunkD5YJHGSTjs = require('./chunk-D5YJHGST.js');
+var _chunkTXVOB5J2js = require('./chunk-TXVOB5J2.js');
 
 
 var _chunk7P5AA3SNjs = require('./chunk-7P5AA3SN.js');
@@ -136,8 +136,8 @@ var BROWSER_OPEN_COOLDOWN_MS = 3e4;
 var SAME_URL_BROWSER_OPEN_COOLDOWN_MS = 5 * 6e4;
 var defaultBrowserCommandRunner = childProcess;
 function getAuthedHttpClient() {
-  const config = _chunkD5YJHGSTjs.resolveConfig.call(void 0, );
-  return { config, http: new (0, _chunkD5YJHGSTjs.HttpClient)(config) };
+  const config = _chunkTXVOB5J2js.resolveConfig.call(void 0, );
+  return { config, http: new (0, _chunkTXVOB5J2js.HttpClient)(config) };
 }
 function stableOsUserId() {
   try {
@@ -477,7 +477,7 @@ function collectLocalEnvInfo() {
     os: `${process.platform} ${process.arch}`,
     node_version: process.version,
     home_dir: homeDir,
-    agent_runtime: _chunkD5YJHGSTjs.detectAgentRuntime.call(void 0, )
+    agent_runtime: _chunkTXVOB5J2js.detectAgentRuntime.call(void 0, )
   };
   const env = process.env;
   const optional = {
@@ -725,9 +725,9 @@ function markdownTableFromRows(rows, preferredColumns = []) {
 }
 function withAgentCommandContext(value) {
   const valueRecord = value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
-  return _chunkD5YJHGSTjs.detectAgentRuntime.call(void 0, ) !== "unknown" && valueRecord && !Object.prototype.hasOwnProperty.call(valueRecord, "command_context") ? {
+  return _chunkTXVOB5J2js.detectAgentRuntime.call(void 0, ) !== "unknown" && valueRecord && !Object.prototype.hasOwnProperty.call(valueRecord, "command_context") ? {
     ...valueRecord,
-    command_context: _chunkD5YJHGSTjs.resolveCliCommandContext.call(void 0, )
+    command_context: _chunkTXVOB5J2js.resolveCliCommandContext.call(void 0, )
   } : value;
 }
 function printJson(value, fields) {

package/dist/cli/{chunk-NIOFMRYW.mjs → chunk-DFDXKOLR.mjs}

@@ -3,11 +3,14 @@ import {
   rateLimitSummary,
   schemaField,
   schemaFields
-} from "./chunk-76VKBPOC.mjs";
+} from "./chunk-JOA6IKDE.mjs";
+import {
+  shellQuote
+} from "./chunk-OVDNJAJN.mjs";
 import {
   recentSearchRef,
   registerDeprecatedSearchCommand
-} from "./chunk-NQJQ3CLX.mjs";
+} from "./chunk-VGKVLADU.mjs";
 import {
   extractSummaryFields,
   projectRowOutput,
@@ -17,8 +20,9 @@ import {
   writeJsonOutputFile
 } from "./chunk-MIMASXO4.mjs";
 import {
-  DeeplineClient
-} from "./chunk-3ZKAKQYC.mjs";
+  DeeplineClient,
+  validateExecutionIdempotencyKey
+} from "./chunk-KLWBAQ5A.mjs";
 import {
   beginToolExecuteCommand,
   getToolExecuteInvocationId,
@@ -26,18 +30,17 @@ import {
   runToolExecuteStage
 } from "./chunk-WXLOW623.mjs";
 import {
-  argsWantJson,
   printCommandEnvelope,
   printCompactJson,
   printJson,
   printJsonError,
   renderCommandEnvelopeText,
   shouldEmitJson
-} from "./chunk-I7RLL7LN.mjs";
+} from "./chunk-M7CPVMDB.mjs";
 import {
   resolveConfig,
   sdkCliStateDirPath
-} from "./chunk-TJGJTB5T.mjs";
+} from "./chunk-BR7GGTAE.mjs";
 import {
   DeeplineError
 } from "./chunk-NXGCO4JB.mjs";
@@ -1010,7 +1013,7 @@ Examples:
         process.exitCode = await narrowView();
         return;
       }
-      const { describeAnything } = await import("./describe-ZAPGM5ND.mjs");
+      const { describeAnything } = await import("./describe-GMVS3LFC.mjs");
       process.exitCode = await describeAnything(
         toolId,
         { ...options, kinds: ["tools", "monitors"], fetchedTool: metadata },
@@ -1025,7 +1028,7 @@ Examples:
       { json: false }
     )
   );
-  tools.command("execute <toolId>").description("Execute a tool by id.").addHelpText(
+  tools.command("execute <toolId>").alias("call").description("Execute a tool by id.").addHelpText(
     "after",
     `
 Notes:
@@ -1084,22 +1087,7 @@ Examples:
     "--recovery-timeout-ms <milliseconds>",
     "Maximum wait for a keyed execution to finish (default: 900000)"
   ).action(async (toolId, options) => {
-    const args = [
-      toolId,
-      ...options.param.flatMap((value) => ["--param", value]),
-      ...options.json === true ? ["--json"] : [],
-      ...typeof options.json === "string" ? ["--json", options.json] : [],
-      ...options.input ? ["--input", options.input] : [],
-      ...options.payload ? ["--payload", options.payload] : [],
-      ...options.timeout ? ["--timeout", options.timeout] : [],
-      ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
-      ...options.out ? ["--out", options.out] : [],
-      ...options.preview === false ? ["--no-preview"] : [],
-      ...options.idempotencyKey ? ["--idempotency-key", options.idempotencyKey] : [],
-      ...options.recover ? ["--recover"] : [],
-      ...options.recoveryTimeoutMs ? ["--recovery-timeout-ms", options.recoveryTimeoutMs] : []
-    ];
-    process.exitCode = await executeTool(args);
+    process.exitCode = await executeTool(toolId, options);
   });
 }
 async function getTool(toolId, options = {}, compatibilityMetadata) {
@@ -1808,6 +1796,7 @@ function printToolExamplesOnly(tool, requestedToolId) {
   console.log(`Use in a play:`);
   console.log("```ts");
   console.log("const result = await ctx.tools.execute({");
+  console.log("  staleAfterSeconds: 0,");
   console.log(`  id: '${stableStepIdForTool(toolId)}',`);
   console.log(`  tool: '${toolId}',`);
   console.log(
@@ -2545,87 +2534,63 @@ function parseJsonObjectArgument(raw, flagName) {
   }
   return parsed;
 }
-function parseExecuteOptions(args) {
-  const toolId = args[0];
+function toolExecuteJsonOption(value) {
+  const legacyInput = typeof value === "string" ? value : void 0;
+  return {
+    requested: value === true || legacyInput !== void 0,
+    legacyInput
+  };
+}
+function parseExecuteOptions(toolId, options, output) {
   if (!toolId) {
     throw new Error(
       `Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--timeout <duration>] [--recover | --idempotency-key <key>] [--recovery-timeout-ms <ms>] [--out rows.csv] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`
     );
   }
   const params = {};
-  let outputFormat = "auto";
-  let noPreview = false;
-  let outPath = null;
-  let timeoutMs;
-  let idempotencyKey;
-  let recover = false;
+  let outputFormat = output.requested ? "json" : "auto";
   let recoveryTimeoutMs;
-  for (let index = 1; index < args.length; index += 1) {
-    const arg = args[index];
-    if ((arg === "--param" || arg === "-p") && args[index + 1]) {
-      const kv = args[++index];
-      const eqIdx = kv.indexOf("=");
-      if (eqIdx > 0) params[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
-      continue;
-    }
-    if (arg === "--json") {
-      const next = args[index + 1];
-      outputFormat = "json";
-      if (next && !next.startsWith("--")) {
-        Object.assign(
-          params,
-          parseJsonObjectArgument(args[++index], "--json")
-        );
-      }
-      continue;
-    }
-    if ((arg === "--input" || arg === "--payload") && args[index + 1]) {
-      Object.assign(params, parseJsonObjectArgument(args[++index], arg));
-      continue;
-    }
-    if (arg === "--timeout" && args[index + 1]) {
-      timeoutMs = parseToolExecuteTimeout(args[++index]);
-      continue;
-    }
-    if (arg === "--output-format" && args[index + 1]) {
-      outputFormat = normalizeOutputFormat(args[++index]);
-      continue;
-    }
-    if (arg === "--no-preview") {
-      noPreview = true;
-      continue;
-    }
-    if (arg === "--idempotency-key" && args[index + 1]) {
-      idempotencyKey = args[++index];
-      continue;
-    }
-    if (arg === "--recover") {
-      recover = true;
-      continue;
-    }
-    if (arg === "--recovery-timeout-ms" && args[index + 1]) {
-      const parsed = Number(args[++index]);
-      if (!Number.isFinite(parsed) || parsed < 0) {
-        throw new Error("--recovery-timeout-ms must be a non-negative number.");
-      }
-      recoveryTimeoutMs = parsed;
-      continue;
-    }
-    if ((arg === "--out" || arg === "-o") && args[index + 1]) {
-      outPath = resolve(args[++index]);
-      continue;
+  for (const kv of options.param ?? []) {
+    const eqIdx = kv.indexOf("=");
+    if (eqIdx > 0) params[kv.slice(0, eqIdx)] = kv.slice(eqIdx + 1);
+  }
+  if (output.legacyInput !== void 0) {
+    Object.assign(
+      params,
+      parseJsonObjectArgument(output.legacyInput, "--json")
+    );
+  }
+  if (options.input !== void 0) {
+    Object.assign(params, parseJsonObjectArgument(options.input, "--input"));
+  }
+  if (options.payload !== void 0) {
+    Object.assign(
+      params,
+      parseJsonObjectArgument(options.payload, "--payload")
+    );
+  }
+  if (options.outputFormat !== void 0) {
+    outputFormat = normalizeOutputFormat(options.outputFormat);
+  }
+  if (options.idempotencyKey !== void 0) {
+    validateExecutionIdempotencyKey(options.idempotencyKey);
+  }
+  if (options.recoveryTimeoutMs !== void 0) {
+    const parsed = Number(options.recoveryTimeoutMs);
+    if (!options.recoveryTimeoutMs.trim() || !Number.isFinite(parsed) || parsed < 0) {
+      throw new Error("--recovery-timeout-ms must be a non-negative number.");
     }
-    throw new Error(`Unknown option: ${arg}`);
+    recoveryTimeoutMs = parsed;
   }
   return {
     toolId,
     params,
     outputFormat,
-    noPreview,
-    outPath,
-    timeoutMs,
-    idempotencyKey,
-    recover,
+    noPreview: options.preview === false,
+    outPath: options.out !== void 0 ? resolve(options.out) : null,
+    timeoutMs: options.timeout !== void 0 ? parseToolExecuteTimeout(options.timeout) : void 0,
+    idempotencyKey: options.idempotencyKey,
+    recover: options.recover === true,
     recoveryTimeoutMs
   };
 }
@@ -2650,9 +2615,6 @@ function parseToolExecuteTimeout(raw) {
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
 }
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function powerShellQuote(value) {
   return `'${value.replace(/'/g, "''")}'`;
 }
@@ -2682,6 +2644,7 @@ function seedToolListScript(input) {
 
 export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   const result = await ctx.tools.execute({
+    staleAfterSeconds: 0,
     id: ${JSON.stringify(input.toolId)},
     tool: ${JSON.stringify(input.toolId)},
     input: ${JSON.stringify(input.payload)},
@@ -2699,7 +2662,7 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   // Pass it to ctx.dataset; use rows.peek/count/materialize only for deliberate bounded inspection.
   // .withColumn('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
   // .withColumn('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
-  // ctx.dataset is idempotent by dataset key + row key; reruns reuse completed rows.
+  // ctx.dataset is idempotent for completed rows during same-run recovery. New runs follow each call's freshness.
   const enrichedData = await ctx
     .dataset('enriched_data', rows)
     .run({
@@ -2724,6 +2687,12 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
     windowsCopyCommand: `New-Item -ItemType Directory -Force -Path ${powerShellQuote(projectDir.replace(/\//g, "\\"))} | Out-Null; Copy-Item -LiteralPath ${powerShellQuote(scriptPath)} -Destination ${powerShellQuote(`${projectDir.replace(/\//g, "\\")}\\${fileName}`)}`
   };
 }
+function toolExecutionInspection(input) {
+  return {
+    inspect: input.idempotencyKey !== void 0 ? `deepline executions get --idempotency-key ${shellQuote(input.idempotencyKey)} --json` : `deepline describe ${shellQuote(input.toolId)} --json`,
+    inspectDescription: input.idempotencyKey !== void 0 ? "Read the saved execution without starting new work." : "Read the tool contract; this unkeyed call has no saved recovery identity."
+  };
+}
 function buildToolExecuteBaseEnvelope(input) {
   const envelope = commandEnvelopeFromRawResponse(input.rawResponse);
   const guidanceLines = toolExecuteExitCode(envelope) !== 0 || input.listExpected === true && !input.listConversion ? toolGuidanceLines(input.guidance) : [];
@@ -2749,7 +2718,7 @@ function buildToolExecuteBaseEnvelope(input) {
     "output"
   );
   const billingLookup = typeof envelope.job_id === "string" && envelope.job_id.trim() ? `deepline billing usage --request-id ${shellQuote(envelope.job_id)} --json` : null;
-  const inspectCommand = `deepline tools execute ${input.toolId} --input ${shellQuote(JSON.stringify(input.params))} --json`;
+  const inspection = toolExecutionInspection(input);
   const actions = input.listConversion ? [
     {
       label: "next",
@@ -2767,6 +2736,7 @@ function buildToolExecuteBaseEnvelope(input) {
   if (billingLookup) {
     actions.push({ label: "charge", command: billingLookup });
   }
+  actions.unshift({ label: "inspect", command: inspection.inspect });
   return {
     ...envelope,
     ...input.idempotencyKey ? { idempotency_key: input.idempotencyKey } : {},
@@ -2775,13 +2745,13 @@ function buildToolExecuteBaseEnvelope(input) {
     ...summaryEntries.length > 0 ? { summary: input.summary } : {},
     ...warningMessages.length > 0 ? { warnings: warningMessages } : {},
     next: {
-      inspect: inspectCommand,
+      ...inspection,
       ...billingLookup ? { billing: billingLookup } : {},
       ...apifyRecovery ?? {},
       ...guidanceLines.length > 0 ? { guidance: input.guidance } : {},
       playDebugging: "When fixing a play getter, inspect returned dataset handles with runs get and export rows with runs export; do not copy CLI preview paths blindly.",
       ...input.listConversion ? {
-        expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
+        expandToPlay: "Use stable map and step keys for recovery within a run. New runs follow each call's explicit freshness.",
         listSourcePath: input.listConversion.sourcePath ?? "auto-detected list in the CLI response preview"
       } : {}
     },
@@ -2832,6 +2802,7 @@ function buildToolExecuteRowArtifactEnvelope(input) {
   void _next;
   void _local;
   const billingLookup = isRecord(input.baseEnvelope.next) && typeof input.baseEnvelope.next.billing === "string" ? input.baseEnvelope.next.billing : null;
+  const inspection = toolExecutionInspection(input);
   return {
     ...base,
     status: typeof base.status === "string" ? base.status : "completed",
@@ -2873,10 +2844,10 @@ function buildToolExecuteRowArtifactEnvelope(input) {
       windows_powershell: input.seededScript.windowsCopyCommand
     },
     next: {
-      inspect: "Re-run with --json only when you need the raw provider/tool response.",
+      ...inspection,
       ...billingLookup ? { billing: billingLookup } : {},
       listSourcePath: input.rowOutput.sourcePath,
-      expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+      expandToPlay: "Use stable map and step keys for recovery within a run. New runs follow each call's explicit freshness."
     },
     render: {
       sections: [
@@ -2893,10 +2864,11 @@ function buildToolExecuteRowArtifactEnvelope(input) {
         }
       ],
       actions: [
+        { label: "inspect", command: inspection.inspect },
         ...billingLookup ? [{ label: "charge", command: billingLookup }] : [],
         {
           label: "next",
-          command: "Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
+          command: "Move the script into a project folder and expand it into a Deepline play. Use stable map and step keys for same-run recovery; choose explicit freshness for calls in new runs."
         },
         {
           label: "macOS/Linux",
@@ -2910,17 +2882,19 @@ function buildToolExecuteRowArtifactEnvelope(input) {
     }
   };
 }
-async function executeTool(args) {
+async function executeTool(toolId, options) {
+  const output = toolExecuteJsonOption(options.json);
+  const wantsJson = shouldEmitJson(output.requested);
   let parsed;
   try {
-    parsed = parseExecuteOptions(args);
+    parsed = parseExecuteOptions(toolId, options, output);
   } catch (error) {
-    if (argsWantJson(args)) {
+    if (wantsJson) {
       printJsonError(error);
     } else {
       console.error(error instanceof Error ? error.message : String(error));
     }
-    return 1;
+    return error instanceof DeeplineError && error.code === "IDEMPOTENCY_KEY_INVALID" ? 2 : 1;
   }
   const cliInvocationId = getToolExecuteInvocationId() ?? beginToolExecuteCommand();
   const client = new DeeplineClient();
@@ -2937,7 +2911,7 @@ async function executeTool(args) {
         () => findPlayForToolId(client, parsed.toolId, cliInvocationId)
       );
       if (play) {
-        if (argsWantJson(args)) {
+        if (wantsJson) {
           printJsonError(
             new Error(playAliasToolErrorMessage(parsed.toolId, play))
           );
@@ -2950,7 +2924,7 @@ async function executeTool(args) {
     throw error;
   }
   if (isPlayLikeTool(metadata)) {
-    if (argsWantJson(args)) {
+    if (wantsJson) {
       printJsonError(
         new Error(
           playLikeToolExecuteErrorMessage(
@@ -2992,7 +2966,7 @@ async function executeTool(args) {
     }).catch((error) => {
       const guidanceLines = toolGuidanceLines(metadata.guidance);
       if (guidanceLines.length > 0) {
-        if (args.includes("--json") && error instanceof Error) {
+        if (wantsJson && error instanceof Error) {
           Object.assign(error, { guidance: metadata.guidance });
         } else {
           console.error(
@@ -3049,10 +3023,14 @@ async function executeTool(args) {
     }
     if (!listConversion) {
       if (parsed.outPath) {
+        const inspection = toolExecutionInspection({
+          toolId: parsed.toolId,
+          idempotencyKey
+        });
         const error = new Error(
-          `${parsed.toolId} did not expose row-shaped output to write as CSV. Re-run with --json to inspect the raw tool response.`
+          `${parsed.toolId} did not expose row-shaped output to write as CSV. ${inspection.inspectDescription} Run: ${inspection.inspect}`
         );
-        if (argsWantJson(args)) {
+        if (wantsJson) {
           printJsonError(error);
         } else {
           console.error(error.message);
@@ -3090,6 +3068,8 @@ async function executeTool(args) {
       rows: listConversion.rows
     });
     const materializedEnvelope = buildToolExecuteRowArtifactEnvelope({
+      toolId: parsed.toolId,
+      idempotencyKey,
       baseEnvelope,
       csv,
       rowOutput,
@@ -3101,9 +3081,14 @@ async function executeTool(args) {
       return true;
     }
     if (parsed.outPath) {
+      const inspection = toolExecutionInspection({
+        toolId: parsed.toolId,
+        idempotencyKey
+      });
       printCommandEnvelope(materializedEnvelope, {
-        json: argsWantJson(args) || shouldEmitJson(),
+        json: wantsJson,
         text: `Wrote ${csv.rowCount} row(s) to ${csv.path}
+inspect: ${inspection.inspect}
 `
       });
       return true;