@thirdfy/agent-cli 0.2.75 → 0.2.77

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.77] - 2026-09-24
+
+### Changed
+
+- **Dependencies on current releases:**
+  - `commander` 14.0.3: 12 → 14 is two majors.
+  - `ethers` 6.17.0 and `@open-wallet-standard/core` 1.4.2.
+  - Commander 15 is held back because it needs Node ≥22.12. agent-cli still supports Node ≥20, and Hermes runtimes install `@latest` on the Node their image already has.
+- **Extra positional arguments are still accepted.** Commander 13+ rejects them by default; the CLI opts back in (`allowExcessArguments`), so a command like `intent-status <id>` behaves as in 0.2.76. Pin: `test/commander-routing.test.cjs`.
+- **`-ni` still works.** Commander 13+ rejects two-letter short flags. The option is `--not-interactive`, and a bare `-ni` is rewritten to it before parsing. Pin: `test/commander-routing.test.cjs`.
+- **`venue readiness|setup|fund` declare `<venue>`.** The manifest passed `true` as the argument name, which commander 12 accepted as one required positional. The behavior is unchanged: `thirdfy-agent venue readiness avantis`.
+- **CI and release:**
+  - CI tests Node 20, 22 and 24.
+  - Release and live e2e run on Node 24.
+  - `actions/checkout@v7`, `actions/setup-node@v7`.
+  - Dependabot with weekly updates.
+- **agent_wallet reads make one API call.** A read in `agent_wallet` mode skips the `/execution-wallet` preflight, because the API resolves the execution wallet itself. The preflight still runs when the read needs its answer: `--wallet-address` set to a wallet other than the agent key, chain 4663 (Robinhood delegated lane), or a Hyperliquid/Lighter/Avantis address default. With `--wallet-address` equal to the agent key, the wallet the API reports is checked after the read (same `EXECUTION_WALLET_MISMATCH` rule). The result shows `executionWalletPreflight: { skipped: "read_fast_path" }`. Matches `thirdfy-mcp` `walletExecute`.
+- **`WRITE_OUTCOME_UNKNOWN` advice matches `thirdfy-mcp`.** The error names the action and the idempotency key: re-read state first; if the write landed, do not resend; if unsure and retrying, reuse the exact same key; if the re-read shows it did not land, send it with a new key. The API holds an unknown-outcome claim for 24 h.
+- **Unknown actions.** An action that is not in the catalog, or not allowed for the agent key, still fails with `error: PARAMS_SCHEMA_INVALID`, now with `blockedReason: UNKNOWN_ACTION`, `resolvedAction: null`, and `suggestions` (closest catalog actions). Same shape as `thirdfy-mcp` 0.1.6.
+- **Write timeout floor (pin only).** The CLI picks write timeouts from its own read/write classifier, not the catalog `behavior.latencyClass`, so a write never gets the read timeout. `test/mcp-api-parity.test.cjs` pins it.
+
+### Security
+
+- **The agent API key never goes in a URL.** The policy-aware actions listing (`thirdfy-agent actions --agent-api-key …`, and action resolution before `run` / `preflight` / `wallet execute`) called `GET /api/v1/agent/actions?agentApiKey=…`. It now sends the key in the `x-agent-api-key` header, which every agent route reads since Thirdfy API 3.15; a key in the query string gets `Deprecation` headers. Pin: `test/mcp-api-parity.test.cjs`.
+
+### Added
+
+- **Replayed writes are labeled.** When the API answers a value-moving write from an earlier identical one (`Idempotent-Replayed: true` header or `idempotentReplay: true` in the body), the result carries `idempotentReplay: true` and a note: nothing new was executed; send a new `executionIdempotencyKey` (`idempotencyKey` on execute-intent) to place another. Both come from `--idempotency-key`. Matches `thirdfy-mcp` `idempotentReplayFields`.
+- **`deposit_earn_position` amount aliases.** `amountHuman` and `amountInHuman` are accepted in place of `amount` (a decimal token-unit string). Two amounts, or raw base units (`amountInRaw`, `amountIn`), fail with `EARN_AMOUNT_*` before any request. **New refusal:** earn deposits that sent `amountIn` / `amountInRaw` used to reach the API, which reads `amount` as token units; they now fail locally. `execute_optimal_swap` takes the same `amountInRaw` / `amountInHuman` + `tokenInDecimals` contract as `swap`. Matches the `thirdfy-mcp` params gate (`earn_deposit_decimal_amount`, `evm_erc20_amount_in`).
+
+## [0.2.76] - 2026-09-23
+
+### Fixed
+
+- Managed writes (perps orders, TP/SL updates, closes) use a 90s HTTP timeout instead of the 30s default. They sign, broadcast, and wait for a receipt in one API call. Reads keep the base timeout; onboarding, earn, and bridge actions keep 180s. Override: `THIRDFY_CLI_WRITE_TIMEOUT_MS` (or `THIRDFY_API_WRITE_TIMEOUT_MS`).
+- `requestJson` resends a timed-out request only when it is a GET, a validation-only preview (`validationOnly` or `executionLane: validation_only`), or marked `writeAction: false` (read rail, build-tx, telemetry, governance preflight, execute-intent preflight). Every other POST (venue fund, delegation, onboarding) returns `WRITE_OUTCOME_UNKNOWN` instead of a second send. Read/write classification uses catalog metadata when the resolved action is available.
+- Avantis market open/close (`place_avantis_perps_order`, `close_avantis_position`) use the 180s long timeout; the API streams, then polls, for up to about 180s.
+- A write whose request times out is not resent. The retry could double a trade that already executed. The CLI throws `WRITE_OUTCOME_UNKNOWN` (`nextAction: reread_state_before_retry`). Preflight (`validationOnly`) and reads still retry once. Pin: `test/actionTimeouts.test.cjs`. Pairs with `thirdfy-mcp` **0.0.125**.
+
 ## [0.2.75] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -40,10 +40,13 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.75
+## What's new in v0.2.77
 
-- World ID deposit proof commands load without a duplicate `--network` flag.
-- `delegation world-id-deposit-begin` accepts amount, runtime, and destination flags.
+- The agent API key is sent in the `x-agent-api-key` header, never in a URL.
+- A write the API answers from an earlier identical one is marked `idempotentReplay: true`. Send a new `--idempotency-key` to place another.
+- `agent_wallet` reads make one API call (no separate wallet preflight when the read does not need it).
+- `deposit_earn_position` accepts `amountHuman` / `amountInHuman` as `amount`. Unknown actions report `blockedReason: UNKNOWN_ACTION` with `suggestions`.
+- Built on commander 14 and ethers 6.17; Node 20+ is still supported.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.75",
+  "version": "0.2.77",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -71,8 +71,8 @@
   },
   "homepage": "https://github.com/thirdfy/agent-cli#readme",
   "dependencies": {
-    "@open-wallet-standard/core": "^1.3.0",
-    "commander": "^12.1.0",
-    "ethers": "^6.16.0"
+    "@open-wallet-standard/core": "^1.4.2",
+    "commander": "^14.0.3",
+    "ethers": "^6.17.0"
   }
 }

package/src/cli/manifest.mjs

@@ -104,7 +104,7 @@ export const CLI_MANIFEST = [
     handler: 'commandVenueReadiness',
     options: ['auth', 'venue'],
     description: 'Normalized venue readiness (polymarket, hyperliquid, lighter, avantis)',
-    args: { query: true },
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {
@@ -112,7 +112,7 @@ export const CLI_MANIFEST = [
     handler: 'commandVenueSetup',
     options: ['auth', 'venue'],
     description: 'Prepare or complete venue onboarding via shared API contract',
-    args: { query: true },
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {
@@ -120,7 +120,7 @@ export const CLI_MANIFEST = [
     handler: 'commandVenueFund',
     options: ['auth', 'venue'],
     description: 'Return venue funding plan (does not move funds implicitly)',
-    args: { query: true },
+    args: { query: '<venue>' },
     tier: 'online',
   },
   {

package/src/cli/options/bootstrap.mjs

@@ -1,3 +1,9 @@
+/** Commander 13+ rejects multi-character short flags; keep the historical `-ni` spelling working. */
+export function normalizeLegacyShortFlags(argv) {
+  const end = argv.indexOf('--');
+  return argv.map((arg, index) => (arg === '-ni' && (end === -1 || index < end) ? '--not-interactive' : arg));
+}
+
 export function attachBootstrapOptions(cmd) {
   return cmd
     .option('--proof-type <type>', 'session_token|wallet_signature')
@@ -10,7 +16,7 @@ export function attachBootstrapOptions(cmd) {
     .option('--otp <otp>', 'email OTP alias')
     .option('--accept-terms', 'accept terms for email login')
     .option('--key-name <name>', 'Privy key name')
-    .option('-ni, --not-interactive', 'fail fast when required login input is missing')
+    .option('--not-interactive', 'fail fast when required login input is missing (alias: -ni)')
     .option('--no-bootstrap-agent', 'skip agent bootstrap on email login')
     .option('--rotate-agent-key', 'rotate agent key')
     .option('--login-attempt-id <id>', 'email login attempt id')

package/src/cli/program.mjs

@@ -3,3 +3,4 @@ import { buildCliProgram } from './register.mjs';
 export { buildCliProgram };
 export { collectRootFlags, collectLegacyFlags } from './flags.mjs';
 export { configureCommanderErrors, handleRootOnlyFlows, collectVersionFlagsFromArgv } from './errors.mjs';
+export { normalizeLegacyShortFlags } from './options/bootstrap.mjs';

package/src/cli/register.mjs

@@ -107,6 +107,9 @@ function registerManifestEntry(program, entry, nodeByPath, deps) {
 export function buildCliProgram(deps) {
   const program = new Command('thirdfy-agent');
   program.name('thirdfy-agent');
+  // Commander 13+ rejects extra positional arguments by default. 0.2.76 (commander 12) ignored them,
+  // and agents that pass an id positionally (`intent-status <id>`) must keep working.
+  program.allowExcessArguments(true);
   attachGlobalOptions(program);
   program.addHelpCommand(false);
   program.showHelpAfterError(false);

package/src/commands/condor.mjs

@@ -108,7 +108,8 @@ export function createCondorCommands({ commandRun, printEnvelope }) {
         ...params,
       },
     };
-    const data = await apiPost(ctx, '/api/v1/agent/governance/preflight', body, {
+    // Preflight only evaluates policy, so a timed-out request is safe to resend.
+    const data = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/governance/preflight', body, {
       'x-agent-api-key': agentApiKey,
     });
     printEnvelope({

package/src/commands/telemetry.mjs

@@ -122,7 +122,7 @@ async function commandTrackAction(ctx, flags, capabilities) {
   if (flags.decision) payload.decision = parseJsonFlag(flags, 'decision');
   if (flags.proof) payload.proof = parseJsonFlag(flags, 'proof');
 
-  const response = await apiPost(ctx, '/api/v1/agent/telemetry/actions', payload);
+  const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/telemetry/actions', payload);
   printEnvelope({
     success: Boolean(response?.success !== false),
     code: response?.success === false ? 'TRACK_ACTION_FAILED' : 'TRACK_ACTION_OK',

package/src/core/actionTimeouts.mjs

@@ -1,4 +1,12 @@
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
+import { isReadOnlyActionName, isReadOnlyResolvedAction } from './readOnlyActions.mjs';
+
+/**
+ * Default HTTP timeout for managed writes. A perps order or TP/SL update signs, broadcasts, and waits
+ * for a receipt inside one API call; that routinely takes longer than a read. Mirrors thirdfy-mcp
+ * `THIRDFY_API_WRITE_TIMEOUT_MS`.
+ */
+const DEFAULT_WRITE_TIMEOUT_MS = 90_000;
 
 const LONG_RUNNING_ACTIONS = new Set([
   'complete_avantis_onboarding',
@@ -21,6 +29,10 @@ const LONG_RUNNING_ACTIONS = new Set([
   'swap',
   'execute_optimal_swap',
   'deposit_hyperliquid_cctp',
+  // Avantis market open/close: the API streams the batched order for up to 90s, then polls its
+  // tracking status for up to 90s more before it answers.
+  'place_avantis_perps_order',
+  'close_avantis_position',
 ]);
 
 function normalizeActionId(action) {
@@ -30,17 +42,51 @@ function normalizeActionId(action) {
     .toLowerCase();
 }
 
-/** Longer HTTP timeout for Avantis/Lighter onboarding, Avantis setup-status compose, and Morpho/Aave earn writes. */
-export function resolveActionTimeoutMs(action, baseTimeoutMs = DEFAULT_TIMEOUT_MS) {
+function positiveEnvMs(...names) {
+  for (const name of names) {
+    const value = Number(process.env[name]);
+    if (Number.isFinite(value) && value > 0) return value;
+  }
+  return null;
+}
+
+/** True when the action changes state (anything the read-only classifier does not claim). */
+export function isWriteAction(action) {
+  const key = normalizeActionId(action);
+  return Boolean(key) && !isReadOnlyActionName(key);
+}
+
+/**
+ * HTTP timeout for one action. Long-running onboarding, earn, bridge, and compose actions get the
+ * long timeout. Other writes get the write timeout (90s). Reads keep the base timeout. Pass
+ * `options.write` when the caller already classified the action (catalog metadata).
+ */
+export function resolveActionTimeoutMs(action, baseTimeoutMs = DEFAULT_TIMEOUT_MS, options = {}) {
   const base = Number.isFinite(baseTimeoutMs) && baseTimeoutMs > 0 ? baseTimeoutMs : DEFAULT_TIMEOUT_MS;
-  if (!LONG_RUNNING_ACTIONS.has(normalizeActionId(action))) return base;
-  const longMs = Number(
-    process.env.THIRDFY_CLI_LONG_TIMEOUT_MS || process.env.THIRDFY_API_LONG_TIMEOUT_MS || 180_000,
-  );
-  const resolvedLong = Number.isFinite(longMs) && longMs > 0 ? longMs : 180_000;
-  return Math.max(base, resolvedLong);
+  if (LONG_RUNNING_ACTIONS.has(normalizeActionId(action))) {
+    const longMs = positiveEnvMs('THIRDFY_CLI_LONG_TIMEOUT_MS', 'THIRDFY_API_LONG_TIMEOUT_MS') ?? 180_000;
+    return Math.max(base, longMs);
+  }
+  const write = typeof options.write === 'boolean' ? options.write : isWriteAction(action);
+  if (write) {
+    const writeMs =
+      positiveEnvMs('THIRDFY_CLI_WRITE_TIMEOUT_MS', 'THIRDFY_API_WRITE_TIMEOUT_MS') ?? DEFAULT_WRITE_TIMEOUT_MS;
+    return Math.max(base, writeMs);
+  }
+  return base;
 }
 
-export function withActionTimeout(ctx, action) {
-  return { ...ctx, timeoutMs: resolveActionTimeoutMs(action, ctx.timeoutMs) };
+/**
+ * Context for one action's HTTP calls. Accepts the action id or the resolved catalog action, whose
+ * metadata can mark a read the name does not. `writeAction` tells `requestJson` not to resend a
+ * write whose request timed out: the API may have broadcast it, so the outcome is unknown until
+ * state is re-read.
+ */
+export function withActionTimeout(ctx, actionOrResolved) {
+  const resolved = actionOrResolved && typeof actionOrResolved === 'object' ? actionOrResolved : null;
+  const action = resolved ? resolved.resolvedAction : actionOrResolved;
+  const write = resolved
+    ? Boolean(normalizeActionId(action)) && !isReadOnlyResolvedAction(resolved)
+    : isWriteAction(action);
+  return { ...ctx, timeoutMs: resolveActionTimeoutMs(action, ctx.timeoutMs, { write }), writeAction: write };
 }

package/src/core/context.mjs

@@ -131,11 +131,11 @@ export async function getCachedActionsCatalog(ctx, flags) {
   if (hit && hit.expiresAt > now) {
     return hit.actions;
   }
-  let endpoint = '/api/v1/agent/actions/catalog';
-  if (policyAware) {
-    endpoint = `/api/v1/agent/actions?agentApiKey=${encodeURIComponent(String(flags.agentApiKey))}`;
-  }
-  const response = await apiGet(ctx, endpoint);
+  // The agent key goes in the `x-agent-api-key` header, never the URL: URLs land in access logs and
+  // proxies, and API 3.15 answers a URL key with Deprecation headers.
+  const response = policyAware
+    ? await apiGet(ctx, '/api/v1/agent/actions', { 'x-agent-api-key': String(flags.agentApiKey) })
+    : await apiGet(ctx, '/api/v1/agent/actions/catalog');
   const actions = extractActions(response);
   catalogCache.set(cacheKey, {
     actions,

package/src/core/hostedRuntimeIdempotency.mjs

@@ -42,3 +42,31 @@ export function wrapWriteIdempotencyKeyForHostedRuntime(existingKey, runtimeId,
   }
   return existing;
 }
+
+/** Told to the caller when the API answered a write from an earlier identical one. */
+export const idempotentReplayNote = (keyArg = 'executionIdempotencyKey') =>
+  `This result is from an earlier identical write; nothing new was executed. Send a new ${keyArg} to place another.`;
+
+export const IDEMPOTENT_REPLAY_NOTE = idempotentReplayNote();
+
+function hasReplayFlag(value, depth) {
+  if (!value || typeof value !== 'object' || depth > 4) return false;
+  if (Array.isArray(value)) return value.some((item) => hasReplayFlag(item, depth + 1));
+  if (value.idempotentReplay === true) return true;
+  return Object.values(value).some((item) => hasReplayFlag(item, depth + 1));
+}
+
+/**
+ * `{ idempotentReplay: true, note }` when the API replayed an earlier write with the same key:
+ * `idempotentReplay: true` anywhere in the body, or an `Idempotent-Replayed: true` header (API
+ * 3.15). The note names the key field to change (`executionIdempotencyKey` on /execute,
+ * `idempotencyKey` on /execute-intent; both come from `--idempotency-key`). Mirrors thirdfy-mcp
+ * `idempotentReplayFields`.
+ */
+export function idempotentReplayFields(data, headers, keyArg) {
+  const header = headers
+    ? Object.entries(headers).find(([name]) => name.toLowerCase() === 'idempotent-replayed')?.[1]
+    : undefined;
+  const replayed = String(header ?? '').trim().toLowerCase() === 'true' || hasReplayFlag(data, 0);
+  return replayed ? { idempotentReplay: true, note: idempotentReplayNote(keyArg) } : {};
+}

package/src/core/http.mjs

@@ -12,6 +12,94 @@ function isRetryableApiStatus(statusCode) {
   return statusCode === 502 || statusCode === 503 || statusCode === 504;
 }
 
+function isTimeoutError(error) {
+  const message = String(error?.message || '').toLowerCase();
+  return error?.name === 'AbortError' || message.includes('abort') || message.includes('timeout');
+}
+
+/** The idempotency key a write body carries, and the field that carries it. */
+function writeIdempotencyKey(init) {
+  try {
+    const body = JSON.parse(String(init?.body || '{}'));
+    const executionKey = String(body?.executionIdempotencyKey || '').trim();
+    if (executionKey) return { key: executionKey, keyArg: 'executionIdempotencyKey', action: body?.action };
+    const intentKey = String(body?.idempotencyKey || '').trim();
+    if (intentKey) return { key: intentKey, keyArg: 'idempotencyKey', action: body?.action };
+    return { key: '', keyArg: 'executionIdempotencyKey', action: body?.action };
+  } catch {
+    return { key: '', keyArg: 'executionIdempotencyKey', action: undefined };
+  }
+}
+
+/**
+ * A write whose request timed out may already be on chain. Resending it can double a trade, so the
+ * caller gets `WRITE_OUTCOME_UNKNOWN` and re-reads state before any retry. The advice matches
+ * thirdfy-mcp `thirdfyWriteOutcomeUnknownPayload`: reusing the same key lets the API answer with
+ * the first write's result if it landed (the API holds an unknown-outcome claim for 24 h).
+ */
+function writeOutcomeUnknownError(route, ctx, cause, init) {
+  const { key, keyArg, action } = writeIdempotencyKey(init);
+  const retryAdvice = key
+    ? ` If it landed, do not send it again. If you cannot tell and retry, reuse this exact ${keyArg} ("${key}") so the API cannot run it twice. If the re-read shows it did not land, send it again with a new ${keyArg}.`
+    : '';
+  const details = `Thirdfy did not answer within ${Math.round(Number(ctx.timeoutMs || 0) / 1000)}s. The write may have executed. Re-read positions, orders, or balances first, and do not resend the same write blindly.${retryAdvice}`;
+  const error = new Error(`WRITE_OUTCOME_UNKNOWN: ${route} timed out after ${ctx.timeoutMs}ms. ${details}`);
+  error.code = 'WRITE_OUTCOME_UNKNOWN';
+  error.statusCode = 504;
+  error.payload = {
+    error: 'WRITE_OUTCOME_UNKNOWN',
+    code: 504,
+    ...(action ? { action: String(action) } : {}),
+    ...(key ? { [keyArg]: key } : {}),
+    details,
+    nextAction: 'reread_state_before_retry',
+    timeoutMs: ctx.timeoutMs,
+  };
+  error.cause = cause;
+  return error;
+}
+
+/**
+ * Response headers a caller may need after `requestJson` returns only the parsed body. Kept off the
+ * body itself so nothing extra is printed. Today: `Idempotent-Replayed` (API 3.15).
+ */
+const responseHeadersByBody = new WeakMap();
+
+const TRACKED_RESPONSE_HEADERS = ['idempotent-replayed'];
+
+function rememberResponseHeaders(data, response) {
+  if (!data || typeof data !== 'object' || typeof response?.headers?.get !== 'function') return;
+  const tracked = {};
+  for (const name of TRACKED_RESPONSE_HEADERS) {
+    const value = response.headers.get(name);
+    if (value !== null && value !== undefined) tracked[name] = String(value);
+  }
+  if (Object.keys(tracked).length) responseHeadersByBody.set(data, tracked);
+}
+
+/** Tracked response headers (lowercase names) for a body returned by `apiGet` / `apiPost`. */
+export function responseHeadersFor(data) {
+  return (data && typeof data === 'object' && responseHeadersByBody.get(data)) || {};
+}
+
+/**
+ * Whether a request that timed out may be sent again. GETs, validation-only previews, and calls the
+ * caller marks `writeAction: false` are safe. Preflight sends `executionLane: validation_only`
+ * (not a `validationOnly` field). Any other POST changes state (an order, a venue funding, a
+ * delegation grant), so the default is not to resend it.
+ */
+function resendAfterTimeoutIsSafe(ctx, init) {
+  if (ctx?.writeAction === true) return false;
+  if (ctx?.writeAction === false) return true;
+  if (String(init?.method || 'GET').toUpperCase() !== 'POST') return true;
+  try {
+    const body = JSON.parse(String(init?.body || '{}'));
+    return body?.validationOnly === true || body?.executionLane === 'validation_only';
+  } catch {
+    return false;
+  }
+}
+
 function isRetryableApiError(error) {
   const statusCode = Number(error?.statusCode || 0);
   const message = String(error?.message || '').toLowerCase();
@@ -58,6 +146,7 @@ async function requestJsonOnce(ctx, route, init) {
     });
     const text = await response.text();
     const data = text ? safeJsonParse(text) : {};
+    rememberResponseHeaders(data, response);
     if (!response.ok) {
       const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
       error.statusCode = response.status;
@@ -77,6 +166,9 @@ export async function requestJson(ctx, route, init) {
       return await requestJsonOnce(ctx, route, init);
     } catch (error) {
       lastError = error;
+      if (isTimeoutError(error) && !resendAfterTimeoutIsSafe(ctx, init)) {
+        throw writeOutcomeUnknownError(route, ctx, error, init);
+      }
       if (attempt === 0 && isRetryableApiError(error)) {
         await sleep(250 + Math.floor(Math.random() * 250));
         continue;

package/src/runtime/actions/selection.mjs

@@ -1,5 +1,6 @@
 import { requireFlag } from '../../core/args.mjs';
 import { getCachedActionsCatalog } from '../../core/context.mjs';
+import { suggestCatalogActions } from '../validation/actionParamsGate.mjs';
 export function createActionSelection({ getTradingProviderHint, formatProviderAmbiguousActionHint, formatProviderUnknownActionHint }) {
 function getActionKey(action) {
   return String(action?.action || action?.id || action?.key || action?.name || '')
@@ -361,7 +362,7 @@ function resolveActionFromRows(requestedAction, actions, flags = {}) {
     .filter((entry) => entry.key);
 
   if (!keyed.length) {
-    return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
+    return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null, suggestions: [] };
   }
 
   const canonicalAliasOverrides = {
@@ -462,7 +463,15 @@ function resolveActionFromRows(requestedAction, actions, flags = {}) {
       )}?${formatProviderAmbiguousActionHint(providerHint)}`
     );
   }
-  return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
+  return {
+    requestedAction,
+    resolvedAction: requestedAction,
+    resolvedActionMeta: null,
+    suggestions: suggestCatalogActions(
+      requestedAction,
+      keyed.map((entry) => ({ ...entry.action, action: entry.key })),
+    ),
+  };
 }
 
   return {

package/src/runtime/execution/amounts.mjs

@@ -3,7 +3,62 @@ import { createCliError } from '../../core/envelope.mjs';
 export function createExecutionAmounts() {
 function shouldApplySwapAmountContract(actionName) {
   const action = String(actionName || '').trim().toLowerCase();
-  return action === 'swap' || /(^|:|-)swap$/.test(action);
+  return action === 'swap' || action === 'execute_optimal_swap' || /(^|:|-)swap$/.test(action);
+}
+
+function normalizeContractActionKey(actionName) {
+  return String(actionName || '').trim().toLowerCase().replace(/_/g, '-');
+}
+
+/** `deposit_earn_position` takes `amount` as a decimal token-unit string (contract `earn_deposit_decimal_amount`). */
+function shouldApplyEarnDepositAmountContract(actionName) {
+  return /(^|:)deposit-earn-position$/.test(normalizeContractActionKey(actionName));
+}
+
+function hasParamValue(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+/**
+ * Accepts `amountHuman` or `amountInHuman` in place of `amount`, as thirdfy-mcp's params gate does
+ * (`earn_deposit_decimal_amount`). Exactly one decimal amount; raw base units are refused, because
+ * the API reads `amount` as token units.
+ */
+function normalizeEarnDepositAmountContract(params) {
+  const hasAmount = hasParamValue(params.amount);
+  const hasAmountHuman = hasParamValue(params.amountHuman);
+  const hasAmountInHuman = hasParamValue(params.amountInHuman);
+  const humanInputs = [hasAmount, hasAmountHuman, hasAmountInHuman].filter(Boolean).length;
+  if (humanInputs > 1) {
+    throw createCliError(
+      'EARN_AMOUNT_AMBIGUOUS',
+      'Provide exactly one earn deposit amount: amount, amountHuman, or amountInHuman.'
+    );
+  }
+  if (humanInputs === 1) {
+    if (hasParamValue(params.amountInRaw) || hasParamValue(params.amountIn)) {
+      throw createCliError(
+        'EARN_AMOUNT_UNIT_AMBIGUOUS',
+        'Provide exactly one earn deposit amount; do not combine amount/amountHuman/amountInHuman with amountInRaw or amountIn.'
+      );
+    }
+    const amount = String(hasAmount ? params.amount : hasAmountHuman ? params.amountHuman : params.amountInHuman).trim();
+    if (!/^\d+(\.\d+)?$/.test(amount)) {
+      throw createCliError(
+        'EARN_AMOUNT_INVALID',
+        'Earn deposits require amount as a decimal token-unit string (example: "100.5").'
+      );
+    }
+    const { amountHuman: _amountHuman, amountInHuman: _amountInHuman, ...rest } = params;
+    return { ...rest, amount };
+  }
+  if (hasParamValue(params.amountInRaw) || hasParamValue(params.amountIn)) {
+    throw createCliError(
+      'EARN_AMOUNT_UNIT_INVALID',
+      'deposit_earn_position expects amount as a decimal token-unit string. Do not pass raw base-unit amountInRaw/amountIn for earn deposits.'
+    );
+  }
+  return params;
 }
 
 function normalizeIntegerRawAmount(input, code = 'AMOUNT_UNIT_INVALID') {
@@ -164,6 +219,11 @@ function normalizeSwapAmountContract(params) {
 
 function prepareActionParamsForFlags(flags, resolvedAction) {
   const parsedParams = parseJsonFlag(flags, 'params');
+  if (shouldApplyEarnDepositAmountContract(resolvedAction)) {
+    flags.__preparedParams = normalizeEarnDepositAmountContract(parsedParams || {});
+    flags.__swapInput = null;
+    return;
+  }
   if (!shouldApplySwapAmountContract(resolvedAction)) {
     flags.__preparedParams = parsedParams;
     flags.__swapInput = null;
@@ -187,6 +247,8 @@ function getPreparedParams(flags) {
     decimalToRawUnits,
     rawUnitsToDecimalString,
     normalizeSwapAmountContract,
+    shouldApplyEarnDepositAmountContract,
+    normalizeEarnDepositAmountContract,
     prepareActionParamsForFlags,
     getPreparedParams,
   };

package/src/runtime/execution/runners.mjs

@@ -9,7 +9,8 @@ import {
   getEffectiveRunMode,
   parseBooleanFlag,
 } from '../../core/runMode.mjs';
-import { apiGet, apiPost } from '../../core/http.mjs';
+import { apiGet, apiPost, responseHeadersFor } from '../../core/http.mjs';
+import { idempotentReplayFields } from '../../core/hostedRuntimeIdempotency.mjs';
 import { withActionTimeout } from '../../core/actionTimeouts.mjs';
 import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import { resolveWalletExecuteChainId } from '../../core/walletExecuteChainId.mjs';
@@ -32,6 +33,7 @@ export function createExecutionRunners(deps) {
     buildBitfinexOnboardingCommand,
     inferBitfinexPermissionProfileFromAction,
     resolveAgentApiKey,
+    resolveAgentKey,
     loadEthers,
     signAndBroadcastWithOws,
     readEffectBalances,
@@ -146,9 +148,52 @@ function normalizeManagedExecuteResponse(response, { preflight, payload, isRead
     shaped?.amountNormalization || shaped?.data?.amountNormalization || null;
   normalized.raw = shaped;
   normalized.idempotencyKey = payload.executionIdempotencyKey || null;
+  // A replay means nothing new ran; say so, or the caller reads it as a fresh fill.
+  if (!isRead) {
+    Object.assign(
+      normalized,
+      idempotentReplayFields(response, responseHeadersFor(response), 'executionIdempotencyKey'),
+    );
+  }
   return normalized;
 }
 
+const ROBINHOOD_MAINNET_CHAIN_ID = 4663;
+
+/** Marker a read on the fast path carries instead of an execution-wallet preflight. */
+const READ_FAST_PATH_PREFLIGHT = Object.freeze({ success: true, skipped: 'read_fast_path' });
+
+/**
+ * agent_wallet reads skip the /execution-wallet preflight: the API resolves the agent's execution
+ * wallet itself, so the extra round trip only matters when a read uses its answer: a strict wallet
+ * match, a funding check, or the Robinhood delegated lane. An expected wallet equal to the agent key
+ * is not a separate wallet to match first; the wallet the API reports is checked after the read.
+ * Mirrors thirdfy-mcp `walletExecute` readFastPath.
+ */
+function shouldUseManagedReadFastPath(flags, resolved, options = {}) {
+  if (!isReadOnlyAction(resolved)) return false;
+  if (options.requireFundingCheck === true) return false;
+  const runMode = String(flags.runMode || 'agent_wallet').trim().toLowerCase();
+  if (runMode !== 'agent_wallet') return false;
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
+  const agentKey = String(typeof resolveAgentKey === 'function' ? resolveAgentKey(flags) : flags.agentKey || '')
+    .trim()
+    .toLowerCase();
+  if (expectedWallet && expectedWallet !== agentKey) return false;
+  let chainId;
+  try {
+    chainId = resolveWalletExecuteChainId({
+      action: String(resolved?.resolvedAction || flags.action || '').trim(),
+      chainId: flags.chainId,
+      params: getPreparedParams(flags),
+    });
+  } catch {
+    // Unresolvable chain (e.g. a CCTP quote without sourceChainId): the preflight path reports it.
+    return false;
+  }
+  return Number(chainId) !== ROBINHOOD_MAINNET_CHAIN_ID;
+}
+
 async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
   const resolvedAction = resolved.resolvedAction;
   if (runMode === 'agent_wallet') {
@@ -192,7 +237,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         runMode: 'self',
         mirrorOnly: false,
       });
-      const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+      const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', payload);
       const normalized = normalizeIntentResponse(response);
       const blockedCount = normalized.blocked || 0;
       if (!normalized.success || blockedCount > 0) {
@@ -240,7 +285,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         mirrorOnly: false,
         hybridWalletMode: options.hybridWalletMode,
       });
-      const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+      const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', payload);
       const normalized = normalizeIntentResponse(response);
       const blockedCount = normalized.blocked || 0;
       if (!normalized.success || blockedCount > 0) {
@@ -267,7 +312,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         mirrorOnly: false,
         hybridWalletMode: 'agent_wallet',
       });
-      const managedResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', managedPayload);
+      const managedResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', managedPayload);
       const managedNormalized = normalizeIntentResponse(managedResponse);
       const mirrorPayload = buildIntentPayload(flags, {
         validationOnly: true,
@@ -277,7 +322,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         mirrorOnly: true,
         hybridWalletMode: 'agent_wallet',
       });
-      const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+      const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', mirrorPayload);
       const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
       return {
         message:
@@ -304,7 +349,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     runMode,
     mirrorOnly: runMode === 'hybrid',
   });
-  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const response = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', payload);
   const normalized = normalizeIntentResponse(response);
   return {
     message: normalized.success
@@ -403,7 +448,7 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
 
 async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'thirdfy') {
   const skipPreflight = Boolean(options?.skipPreflight);
-  const actionCtx = withActionTimeout(ctx, resolved.resolvedAction);
+  const actionCtx = withActionTimeout(ctx, resolved);
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
@@ -413,7 +458,12 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
       mirrorOnly: false,
       hybridWalletMode: options?.hybridWalletMode,
     });
-    const preflight = await apiPost(actionCtx, '/api/v1/agent/execute-intent', preflightPayload);
+    // validationOnly never writes, so a timed-out preflight is safe to resend.
+    const preflight = await apiPost(
+      { ...actionCtx, writeAction: false },
+      '/api/v1/agent/execute-intent',
+      preflightPayload,
+    );
     const preflightNormalized = normalizeIntentResponse(preflight);
     const blockedCount = preflightNormalized.blocked || 0;
     if (!preflightNormalized.success || blockedCount > 0) {
@@ -434,6 +484,9 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
   const response = await apiPost(actionCtx, '/api/v1/agent/execute-intent', payload);
   const normalized = normalizeIntentResponse(response);
   normalized.idempotencyKey = payload.idempotencyKey;
+  if (!isReadOnlyAction(resolved)) {
+    Object.assign(normalized, idempotentReplayFields(response, responseHeadersFor(response), 'idempotencyKey'));
+  }
   return normalized;
 }
 
@@ -460,7 +513,7 @@ async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, pre
   intentResult.routeFallback = 'execute_intent_read_only';
   if (preflight) {
     intentResult.executionWalletPreflight = preflight;
-    intentResult.executionWalletAddress = preflight.executionWalletAddress || null;
+    intentResult.executionWalletAddress = preflight.executionWalletAddress || intentResult.executionWalletAddress || null;
   }
   intentResult.signerMethod = 'managed_wallet_server';
   return intentResult;
@@ -474,8 +527,11 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
   // (often as a JSON string under data.result). Reads skip funding gates; routing still fails closed.
   const isRead = isReadOnlyAction(resolved);
   const skipPreflight = Boolean(options?.skipPreflight);
-  let preflight = null;
-  if (!skipPreflight) {
+  // A seeded preflight (Hyperliquid/Lighter/Avantis address defaults) already ran; reuse it.
+  const readFastPath =
+    !skipPreflight && !options?.managedPreflight && shouldUseManagedReadFastPath(flags, resolved, options);
+  let preflight = readFastPath ? READ_FAST_PATH_PREFLIGHT : null;
+  if (!skipPreflight && !readFastPath) {
     preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
       runMode: 'agent_wallet',
       requireFundingCheck: !isRead,
@@ -503,10 +559,21 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
     runMode: 'agent_wallet',
     forceIdempotency: true,
   });
-  const actionCtx = withActionTimeout(ctx, resolved.resolvedAction);
+  const actionCtx = withActionTimeout(ctx, resolved);
   const response = await apiPost(actionCtx, '/api/v1/agent/execute', payload);
+  if (readFastPath) {
+    const mismatch = fastPathWalletMismatch(flags, response);
+    if (mismatch) return mismatch;
+  }
   if (shouldFallbackAgentWalletToExecuteIntent(resolved, response)) {
-    const intentResult = await runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, preflight);
+    // On the fast path the wallet comes from the /execute answer, not a preflight.
+    const fallbackPreflight = readFastPath
+      ? {
+          ...READ_FAST_PATH_PREFLIGHT,
+          executionWalletAddress: response?.executionWalletAddress || response?.data?.executionWalletAddress || null,
+        }
+      : preflight;
+    const intentResult = await runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, fallbackPreflight);
     if (isEmptyQueuedExecuteIntent(intentResult.raw || intentResult)) {
       intentResult.success = false;
       intentResult.status = 'failed';
@@ -522,6 +589,33 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
   return normalizeManagedExecuteResponse(response, { preflight, payload, isRead });
 }
 
+/**
+ * The fast path only runs when the expected wallet is empty or equals the agent key. The preflight
+ * path refuses a wallet that differs from the execution wallet, so apply the same rule to the wallet
+ * the API reports for the read.
+ */
+function fastPathWalletMismatch(flags, response) {
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
+  if (!expectedWallet || parseBooleanFlag(flags.allowWalletMismatch, false)) return null;
+  const apiWallet = String(response?.executionWalletAddress || response?.data?.executionWalletAddress || '')
+    .trim()
+    .toLowerCase();
+  if (!apiWallet || apiWallet === expectedWallet) return null;
+  const normalized = normalizeIntentResponse({
+    success: false,
+    status: 'failed',
+    mode: 'agent_wallet',
+    blockedReason: 'EXECUTION_WALLET_MISMATCH',
+    blockedStage: 'routing',
+    error: `Funded wallet (${expectedWallet}) does not match execution wallet (${apiWallet}). Use --allow-wallet-mismatch to override.`,
+    preflightBlocked: true,
+    executionWalletAddress: apiWallet,
+  });
+  normalized.executionWalletAddress = apiWallet;
+  normalized.executionWalletPreflight = READ_FAST_PATH_PREFLIGHT;
+  return normalized;
+}
+
 async function executeSelfRun(ctx, flags, resolved, options) {
   const skipPreflight = Boolean(options?.skipPreflight);
   const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
@@ -539,7 +633,7 @@ async function executeSelfRun(ctx, flags, resolved, options) {
       runMode: 'self',
       mirrorOnly: false,
     });
-    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflight = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', preflightPayload);
     const preflightNormalized = normalizeIntentResponse(preflight);
     const blockedCount = preflightNormalized.blocked || 0;
     if (!preflightNormalized.success || blockedCount > 0) {
@@ -561,7 +655,8 @@ async function executeSelfRun(ctx, flags, resolved, options) {
     return normalized;
   }
   const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
-  const buildTx = await apiPost(ctx, '/api/v1/agent/build-tx', buildTxPayload);
+  // build-tx returns an unsigned transaction; nothing is broadcast, so a timeout may be resent.
+  const buildTx = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/build-tx', buildTxPayload);
   return normalizeIntentResponse({
     ...buildTx,
     status: buildTx?.status || 'ready',
@@ -598,7 +693,7 @@ async function executeHybridRun(ctx, flags, resolved, options) {
       mirrorOnly: true,
       hybridWalletMode,
     });
-    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+    const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', mirrorPayload);
     const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
     return normalizeIntentResponse({
       success: Boolean(managedResult.success && mirrorNormalized.success),
@@ -624,7 +719,7 @@ async function executeHybridRun(ctx, flags, resolved, options) {
     runMode: 'hybrid',
     mirrorOnly: true,
   });
-  const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+  const mirrorResponse = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/execute-intent', mirrorPayload);
   const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
   return normalizeIntentResponse({
     success: Boolean(selfResult.success && mirrorNormalized.success),

package/src/runtime/main.mjs

@@ -6,6 +6,7 @@ import {
   collectRootFlags,
   handleRootOnlyFlows,
   collectVersionFlagsFromArgv,
+  normalizeLegacyShortFlags,
 } from '../cli/program.mjs';
 import { createInitialRuntimeContext, applyFlagsToRuntimeContext } from './context.mjs';
 import { createProviderHints } from './providerHints.mjs';
@@ -87,6 +88,7 @@ export function createThirdfyAgentRuntime() {
     buildBitfinexOnboardingCommand: onboarding.buildBitfinexOnboardingCommand,
     inferBitfinexPermissionProfileFromAction: onboarding.inferBitfinexPermissionProfileFromAction,
     resolveAgentApiKey: payloads.resolveAgentApiKey,
+    resolveAgentKey: payloads.resolveAgentKey,
     loadEthers: ows.loadEthers,
     signAndBroadcastWithOws: ows.signAndBroadcastWithOws,
     readEffectBalances: ows.readEffectBalances,
@@ -154,7 +156,7 @@ export function createThirdfyAgentRuntime() {
     }
 
     try {
-      await cliProgram.parseAsync(process.argv, { from: 'node' });
+      await cliProgram.parseAsync(normalizeLegacyShortFlags(process.argv), { from: 'node' });
       const versionHandled = await handleRootOnlyFlows(cliProgram, rootFlowDeps);
       if (versionHandled) return;
     } catch (error) {

package/src/runtime/validation/actionParamsGate.mjs

@@ -6,6 +6,47 @@ import {
   formatParamsSchemaValidationResult,
 } from './paramsSchema.mjs';
 
+const tokensOf = (action) =>
+  String(action || '')
+    .toLowerCase()
+    .split(/[-_\s]+/)
+    .filter(Boolean);
+
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
+/**
+ * Catalog actions closest to an unknown name: shared words first, then edit distance, so
+ * `open_avantis_position` suggests `place_avantis_perps_order` and typos find their action.
+ * Mirrors thirdfy-mcp `suggestCatalogActions`.
+ */
+export function suggestCatalogActions(requested, actions, limit = 5) {
+  const wanted = tokensOf(requested);
+  const target = wanted.join('_');
+  return (Array.isArray(actions) ? actions : [])
+    .filter((action) => action?.action && action.enabled !== false)
+    .map((action) => {
+      const name = tokensOf(action.action).join('_');
+      const shared = tokensOf(action.action).filter((token) => wanted.includes(token)).length;
+      return { name: action.action, shared, distance: editDistance(target, name) };
+    })
+    .filter((candidate) => candidate.shared > 0 || candidate.distance <= 3)
+    .sort((a, b) => b.shared - a.shared || a.distance - b.distance)
+    .slice(0, limit)
+    .map((candidate) => candidate.name);
+}
+
 export function resolveActionParamsSchema(resolved) {
   const meta = resolved?.resolvedActionMeta;
   if (!meta || typeof meta !== 'object') return null;
@@ -19,12 +60,22 @@ export function isReadOnlyCatalogAction(resolved) {
 export function validateResolvedActionParams(resolved, params) {
   const meta = resolved?.resolvedActionMeta;
   if (!meta || typeof meta !== 'object') {
+    // Same shape as thirdfy-mcp 0.1.6+: `error` stays PARAMS_SCHEMA_INVALID (callers match on it);
+    // `blockedReason: UNKNOWN_ACTION` plus `suggestions` point at real actions. With an agent key
+    // the list is the agent's own policy list, so the action may exist but not be allowed.
+    const suggestions = Array.isArray(resolved?.suggestions) ? resolved.suggestions : [];
     return {
       valid: false,
       skipped: false,
-      error: `Action "${resolved?.requestedAction || ''}" was not found in the Thirdfy catalog`,
+      error: `Action "${resolved?.requestedAction || ''}" is not in the Thirdfy catalog or is not allowed for this agent${
+        suggestions.length
+          ? `. Did you mean: ${suggestions.join(', ')}?`
+          : '. Use `thirdfy-agent actions` to list actions.'
+      }`,
       field: null,
       code: 'PARAMS_SCHEMA_INVALID',
+      blockedReason: 'UNKNOWN_ACTION',
+      suggestions,
     };
   }
 
@@ -57,11 +108,13 @@ export function enforceCatalogActionParams(resolved, flags, getPreparedParams) {
     return;
   }
   throw createCliError('PARAMS_SCHEMA_INVALID', result.error || 'Action params failed catalog schema validation', {
-    blockedReason: 'PARAMS_SCHEMA_INVALID',
+    blockedReason: result.blockedReason || 'PARAMS_SCHEMA_INVALID',
+    ...(Array.isArray(result.suggestions) ? { suggestions: result.suggestions } : {}),
     blockedStage: 'client_validation',
     validationError: result.error || null,
     field: result.field || null,
-    resolvedAction: resolved?.resolvedAction || null,
+    // An unknown action resolved to nothing; MCP reports `resolvedAction: null` for it too.
+    resolvedAction: result.blockedReason === 'UNKNOWN_ACTION' ? null : resolved?.resolvedAction || null,
     requestedAction: resolved?.requestedAction || null,
   });
 }