@thirdfy/agent-cli 0.2.34 → 0.2.36

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.36] - 2026-07-25
+
+### Fixed
+
+- `--run-mode agent_wallet` market-data reads use `/api/v1/agent/execute` again and keep the provider payload on the CLI envelope (`raw` plus coerced `data.result`). Version 0.2.34 routed every managed read through `/execute-intent` to avoid an execution-shaped reply, but solo Hermes `agent_wallet` intents come back as an empty queued envelope with no Hyperliquid universe. Live `/execute` still returns the meta payload (often as a JSON string under `data.result`); the CLI now parses that string so EarnClaw pack parsers can find `universe`. Execute-intent remains the fallback only when the execute rail rejects the action (`does not support execute rail`).
+- **MCP parity:** the same rail fix belongs in `thirdfy-mcp` (`walletExecute`) as **0.0.79**. See workspace rule `cli-mcp-parity` and API docs-dev `cli-mcp-parity.md`.
+
+### Changed
+
+- Reads still skip execution-wallet funding checks. Routing and identity preflight still fail closed.
+
+## [0.2.35] - 2026-07-25
+
+### Fixed
+
+- Read-only detection now matches the Thirdfy API action manifest instead of a narrower client-side guess. `fetch_*`, `show_*`, `dogeos_get_*`, `*_info`, `dogeos_barkswap_get_quote`, `dogeos_laika_read_contract`, and `dogeos_laika_token_state` were previously classified as writes, so under `--run-mode agent_wallet` they went to the execute rail and came back as execution envelopes rather than data. A test now pins the two lists together so they cannot drift apart again.
+- `--run-mode self` and `--run-mode hybrid` serve read-only actions from the read rail. Previously a read under `self` either failed with `SELF_MODE_REQUIRES_BUILD_TX` or, when catalog metadata was missing, asked `/api/v1/agent/build-tx` to build a transaction for a market-data query. Under `hybrid` the payload was nested beneath `managed`, where callers reading `results` could not find it, and a mirror failure could mark a successful read as failed.
+- `normalizeIntentResponse` no longer drops top-level `data` and `raw`. It is a whitelist, and read responses carry their payload in `data`, so a caller could receive a well-formed envelope with nothing in it.
+
+### Changed
+
+- Bitfinex reads under `--run-mode hybrid` are served from the delegated rail instead of returning `HYBRID_MODE_REQUIRES_BUILD_TX` with a hint to rerun using `--run-mode thirdfy`. The guard still applies to Bitfinex writes.
+
 ## [0.2.34] - 2026-07-25
 
 ### Fixed

package/README.md

@@ -40,10 +40,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.34
+## What's new in v0.2.36
 
-- Read-only actions (`get_*`, `list_*`, `search_*`) requested with `--run-mode agent_wallet` now return the provider payload directly instead of an execution envelope. Market data reads such as `get_hyperliquid_perps_meta` no longer come back wrapped as an intent.
-- Reads are no longer gated on execution-wallet funding. The execution address is still reported, but an unfunded wallet does not block a read. Routing and identity checks still apply.
+- `--run-mode agent_wallet` market-data reads (`get_hyperliquid_perps_meta` and siblings) keep the live provider payload from `/api/v1/agent/execute`, including stringified `data.result` coercion, so pack callers can parse the Hyperliquid universe again.
+- Execute-intent is only used for managed reads when the execute rail rejects the action. Solo agent_wallet intents no longer replace a successful market-data reply with an empty queue.
+- Reads still skip funding checks; routing and identity preflight still fail closed.
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/src/core/readOnlyActions.mjs

@@ -0,0 +1,46 @@
+/**
+ * Read-only action classification.
+ *
+ * This mirrors `isReadOnlyAction` in the Thirdfy API
+ * (`src/services/agents/execution/catalog/actionContractManifest.ts`). Keep the two in sync: when the
+ * client and the server disagree about what counts as a read, reads get sent to the managed-wallet
+ * execute rail and come back shaped as an execution envelope instead of provider data.
+ */
+
+const READ_ONLY_PREFIXES = ['get_', 'list_', 'fetch_', 'search_', 'show_', 'dogeos_get_'];
+
+const READ_ONLY_EXACT = new Set([
+  'dogeos_barkswap_get_quote',
+  'dogeos_laika_read_contract',
+  'dogeos_laika_token_state',
+]);
+
+export function normalizeActionKey(actionKey) {
+  return String(actionKey || '')
+    .trim()
+    .toLowerCase()
+    .replace(/-/g, '_');
+}
+
+export function isReadOnlyActionName(actionKey) {
+  const key = normalizeActionKey(actionKey);
+  if (!key) return false;
+  if (READ_ONLY_EXACT.has(key)) return true;
+  if (key.endsWith('_info')) return true;
+  return READ_ONLY_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+/**
+ * Catalog metadata can mark an action read-only even when the name does not match. Production
+ * defaults set `supportsExecute: true` on nearly everything, so this rarely fires on its own.
+ */
+export function isReadOnlyActionMeta(meta) {
+  if (!meta || typeof meta !== 'object') return false;
+  return meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
+}
+
+export function isReadOnlyResolvedAction(resolved, options = {}) {
+  const meta = resolved?.resolvedActionMeta;
+  if (options.requireMeta && (!meta || typeof meta !== 'object')) return false;
+  return isReadOnlyActionName(resolved?.resolvedAction) || isReadOnlyActionMeta(meta);
+}

package/src/runtime/execution/runners.mjs

@@ -11,6 +11,7 @@ import {
 } from '../../core/runMode.mjs';
 import { apiGet, apiPost } from '../../core/http.mjs';
 import { withActionTimeout } from '../../core/actionTimeouts.mjs';
+import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -80,24 +81,7 @@ function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedActio
 }
 
 function isReadOnlyAction(resolved) {
-  const meta = resolved?.resolvedActionMeta || {};
-  const action = String(resolved?.resolvedAction || '')
-    .trim()
-    .toLowerCase()
-    .replace(/-/g, '_');
-  const readOnlyByName =
-    action.startsWith('get_') || action.startsWith('search_') || action.startsWith('list_');
-  const readOnlyByMeta = meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
-  return readOnlyByName || readOnlyByMeta;
-}
-
-// Reads carry no transaction, so wallet balance never blocks them. Every other preflight failure
-// (identity, routing, wallet mismatch) still fails closed, same as a write.
-const FUNDING_ONLY_PREFLIGHT_BLOCKS = new Set(['INSUFFICIENT_FUNDS', 'INVALID_FUNDING_BALANCE']);
-
-function isFundingOnlyPreflightBlock(preflight) {
-  const reason = String(preflight?.blockedReason || '').trim().toUpperCase();
-  return FUNDING_ONLY_PREFLIGHT_BLOCKS.has(reason);
+  return isReadOnlyResolvedAction(resolved);
 }
 
 function shouldFallbackAgentWalletToExecuteIntent(resolved, response) {
@@ -106,6 +90,62 @@ function shouldFallbackAgentWalletToExecuteIntent(resolved, response) {
   return err.includes('does not support execute rail');
 }
 
+// Managed /execute often returns provider payloads as JSON strings under data.result. Pack parsers
+// (and find_value_by_key) need a real object tree, so coerce strings that look like JSON.
+function coerceJsonTreeValue(value) {
+  if (typeof value !== 'string') return value;
+  const trimmed = value.trim();
+  if (!trimmed || (trimmed[0] !== '{' && trimmed[0] !== '[')) return value;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+
+function shapeManagedExecuteReadResponse(response) {
+  if (!response || typeof response !== 'object') return response;
+  const data =
+    response.data && typeof response.data === 'object' ? { ...response.data } : response.data;
+  if (data && typeof data === 'object' && Object.prototype.hasOwnProperty.call(data, 'result')) {
+    data.result = coerceJsonTreeValue(data.result);
+  }
+  return { ...response, data };
+}
+
+function normalizeManagedExecuteResponse(response, { preflight, payload, isRead }) {
+  const shaped = isRead ? shapeManagedExecuteReadResponse(response) : response;
+  const normalized = normalizeIntentResponse({
+    success: Boolean(shaped?.success),
+    status: shaped?.success ? 'completed' : 'failed',
+    mode: 'agent_wallet',
+    txHash: shaped?.txHash || null,
+    blockedReason: shaped?.blockedReason || shaped?.data?.blockedReason || null,
+    blockedStage: shaped?.blockedStage || shaped?.data?.blockedStage || null,
+    error: shaped?.error || null,
+    executionWalletAddress:
+      shaped?.executionWalletAddress || shaped?.data?.executionWalletAddress || null,
+    signerMethod: 'managed_wallet_server',
+    idempotencyKey: payload.executionIdempotencyKey || null,
+    executionWalletPreflight: preflight,
+    amountNormalization:
+      shaped?.amountNormalization || shaped?.data?.amountNormalization || null,
+    // Reads must keep provider payload on the envelope. EarnClaw packs parse
+    // data.raw.data.result (see parse_thirdfy_action_result).
+    ...(isRead && shaped?.data !== undefined ? { data: shaped.data } : {}),
+    raw: shaped,
+  });
+  normalized.executionWalletAddress =
+    shaped?.executionWalletAddress || shaped?.data?.executionWalletAddress || null;
+  normalized.signerMethod = 'managed_wallet_server';
+  normalized.executionWalletPreflight = preflight;
+  normalized.amountNormalization =
+    shaped?.amountNormalization || shaped?.data?.amountNormalization || null;
+  normalized.raw = shaped;
+  normalized.idempotencyKey = payload.executionIdempotencyKey || null;
+  return normalized;
+}
+
 async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
   const resolvedAction = resolved.resolvedAction;
   if (runMode === 'agent_wallet') {
@@ -139,6 +179,34 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     };
   }
   if (runMode === 'self') {
+    // Reads have no unsigned tx to prepare. Keep preflight on validation-only execute-intent so
+    // operators dry-running self mode do not trigger a real catalog read (run still uses the read rail).
+    if (isReadOnlyAction(resolved)) {
+      const payload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        runMode: 'self',
+        mirrorOnly: false,
+      });
+      const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+      const normalized = normalizeIntentResponse(response);
+      const blockedCount = normalized.blocked || 0;
+      if (!normalized.success || blockedCount > 0) {
+        normalized.success = false;
+        normalized.error = normalized.error || 'Preflight blocked self execution';
+        normalized.preflightBlocked = true;
+      }
+      return {
+        message: normalized.success
+          ? 'Self preflight completed'
+          : normalized.preflightBlocked
+            ? 'Self preflight blocked by governance'
+            : 'Self preflight failed',
+        route: 'execute_intent_validation',
+        normalized,
+      };
+    }
     const route = shouldUseBuildTxPreflight(runMode, resolved) ? 'build_tx' : 'execute_intent_validation';
     const normalized = await executeSelfRun(
       ctx,
@@ -157,43 +225,74 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
       normalized,
     };
   }
-  if (runMode === 'hybrid' && options.hybridWalletMode === 'agent_wallet') {
-    const managedPayload = buildIntentPayload(flags, {
-      validationOnly: true,
-      forceIdempotency: false,
-      resolvedAction,
-      runMode: 'agent_wallet',
-      mirrorOnly: false,
-      hybridWalletMode: 'agent_wallet',
-    });
-    const managedResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', managedPayload);
-    const managedNormalized = normalizeIntentResponse(managedResponse);
-    const mirrorPayload = buildIntentPayload(flags, {
-      validationOnly: true,
-      forceIdempotency: false,
-      resolvedAction,
-      runMode: 'hybrid',
-      mirrorOnly: true,
-      hybridWalletMode: 'agent_wallet',
-    });
-    const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
-    const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
-    return {
-      message:
-        managedNormalized.success && mirrorNormalized.success
-          ? 'Hybrid preflight completed (agent_wallet + thirdfy mirror)'
-          : 'Hybrid preflight failed (agent_wallet + thirdfy mirror)',
-      route: 'execute_intent_validation_dual',
-      normalized: normalizeIntentResponse({
-        success: Boolean(managedNormalized.success && mirrorNormalized.success),
-        status: mirrorNormalized.status || managedNormalized.status || 'failed',
-        mode: 'hybrid',
+  if (runMode === 'hybrid') {
+    // Reads have nothing to mirror and need no wallet. Keep preflight on validation-only
+    // execute-intent so dry-runs do not trigger a real catalog read (run still uses the read rail).
+    if (isReadOnlyAction(resolved)) {
+      const payload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        runMode: 'hybrid',
+        mirrorOnly: false,
+        hybridWalletMode: options.hybridWalletMode,
+      });
+      const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+      const normalized = normalizeIntentResponse(response);
+      const blockedCount = normalized.blocked || 0;
+      if (!normalized.success || blockedCount > 0) {
+        normalized.success = false;
+        normalized.error = normalized.error || 'Preflight blocked hybrid execution';
+        normalized.preflightBlocked = true;
+      }
+      return {
+        message: normalized.success
+          ? 'Hybrid preflight completed'
+          : normalized.preflightBlocked
+            ? 'Hybrid preflight blocked by governance'
+            : 'Hybrid preflight failed',
+        route: 'execute_intent_validation',
+        normalized,
+      };
+    }
+    if (options.hybridWalletMode === 'agent_wallet') {
+      const managedPayload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        runMode: 'agent_wallet',
+        mirrorOnly: false,
         hybridWalletMode: 'agent_wallet',
-        managed: managedNormalized,
-        mirror: mirrorNormalized,
-        error: managedNormalized.error || mirrorNormalized.error || null,
-      }),
-    };
+      });
+      const managedResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', managedPayload);
+      const managedNormalized = normalizeIntentResponse(managedResponse);
+      const mirrorPayload = buildIntentPayload(flags, {
+        validationOnly: true,
+        forceIdempotency: false,
+        resolvedAction,
+        runMode: 'hybrid',
+        mirrorOnly: true,
+        hybridWalletMode: 'agent_wallet',
+      });
+      const mirrorResponse = await apiPost(ctx, '/api/v1/agent/execute-intent', mirrorPayload);
+      const mirrorNormalized = normalizeIntentResponse(mirrorResponse);
+      return {
+        message:
+          managedNormalized.success && mirrorNormalized.success
+            ? 'Hybrid preflight completed (agent_wallet + thirdfy mirror)'
+            : 'Hybrid preflight failed (agent_wallet + thirdfy mirror)',
+        route: 'execute_intent_validation_dual',
+        normalized: normalizeIntentResponse({
+          success: Boolean(managedNormalized.success && mirrorNormalized.success),
+          status: mirrorNormalized.status || managedNormalized.status || 'failed',
+          mode: 'hybrid',
+          hybridWalletMode: 'agent_wallet',
+          managed: managedNormalized,
+          mirror: mirrorNormalized,
+          error: managedNormalized.error || mirrorNormalized.error || null,
+        }),
+      };
+    }
   }
   const payload = buildIntentPayload(flags, {
     validationOnly: true,
@@ -249,14 +348,20 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   if (runMode === 'self') {
     const normalized = await executeSelfRun(ctx, flags, resolved, options);
     const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
+    const readOnlySuccess =
+      normalized.success && normalized.routeFallback === 'execute_intent_read_only';
     return {
       code: normalized.success
-        ? 'SELF_UNSIGNED_TX_READY'
+        ? readOnlySuccess
+          ? 'SELF_READ_COMPLETED'
+          : 'SELF_UNSIGNED_TX_READY'
         : preflightBlocked
           ? 'PREFLIGHT_BLOCKED'
           : 'SELF_EXECUTION_FAILED',
       message: normalized.success
-        ? 'Unsigned transaction prepared for self-custody execution'
+        ? readOnlySuccess
+          ? 'Read-only action completed via delegated execute-intent'
+          : 'Unsigned transaction prepared for self-custody execution'
         : preflightBlocked
           ? 'Preflight blocked self execution'
           : 'Self-custody execution failed',
@@ -269,12 +374,22 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
   const hybridWalletMode = normalizeHybridWalletMode(
     normalized.hybridWalletMode || options?.hybridWalletMode || flags.hybridWalletMode || 'self',
   );
+  const readOnlySuccess =
+    normalized.success && normalized.routeFallback === 'execute_intent_read_only';
   return {
-    code: normalized.success ? 'HYBRID_READY' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'HYBRID_FAILED',
+    code: normalized.success
+      ? readOnlySuccess
+        ? 'HYBRID_READ_COMPLETED'
+        : 'HYBRID_READY'
+      : preflightBlocked
+        ? 'PREFLIGHT_BLOCKED'
+        : 'HYBRID_FAILED',
     message: normalized.success
-      ? hybridWalletMode === 'agent_wallet'
-        ? 'Hybrid execution prepared (agent wallet + mirror preflight)'
-        : 'Hybrid execution prepared (self tx + mirror preflight)'
+      ? readOnlySuccess
+        ? 'Read-only action completed via delegated execute-intent'
+        : hybridWalletMode === 'agent_wallet'
+          ? 'Hybrid execution prepared (agent wallet + mirror preflight)'
+          : 'Hybrid execution prepared (self tx + mirror preflight)'
       : preflightBlocked
         ? 'Preflight blocked hybrid execution'
         : 'Hybrid execution failed',
@@ -319,7 +434,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
   return normalized;
 }
 
-async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, preflight) {
+async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, preflight, reportedMode = 'agent_wallet') {
   const userDid = resolveEffectiveUserDid(flags, {
     runMode: 'agent_wallet',
     hybridWalletMode: options?.hybridWalletMode,
@@ -338,7 +453,7 @@ async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, pre
     { ...options, skipPreflight: true },
     'thirdfy'
   );
-  intentResult.mode = 'agent_wallet';
+  intentResult.mode = reportedMode;
   intentResult.routeFallback = 'execute_intent_read_only';
   if (preflight) {
     intentResult.executionWalletPreflight = preflight;
@@ -349,44 +464,18 @@ async function runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, pre
 }
 
 async function executeManagedWalletRun(ctx, flags, resolved, options) {
-  // Read-only actions carry no transaction. Routing them through the managed-wallet execute rail
-  // returns an execution envelope instead of the queried data, which silently starves callers that
-  // asked for market state (see earnclaw-api HL universe probe regression, 2026-07-25).
-  // The wallet address is still resolved for response parity, but a read is never gated on funding.
-  if (isReadOnlyAction(resolved)) {
-    // Do not swallow lookup/routing errors: writes let them propagate, and reads must fail closed
-    // the same way (wallet mismatch, missing identity, failed /execution-wallet).
-    const readPreflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
-      runMode: 'agent_wallet',
-      requireFundingCheck: false,
-      preflightSeed: options?.managedPreflight,
-    });
-    // Funding is intentionally skipped for reads (`requireFundingCheck: false`), but routing
-    // failures (wallet mismatch, missing identity, failed address seed) must still fail closed.
-    if (readPreflight && readPreflight.success === false && !isFundingOnlyPreflightBlock(readPreflight)) {
-      const normalized = normalizeIntentResponse({
-        success: false,
-        status: 'failed',
-        mode: 'agent_wallet',
-        blockedReason: readPreflight.blockedReason || 'PRECHECK_FAILED',
-        blockedStage: readPreflight.blockedStage || 'routing',
-        error: readPreflight.error || 'Managed wallet preflight failed',
-        preflightBlocked: true,
-        executionWalletAddress: readPreflight.executionWalletAddress || null,
-        executionWalletPreflight: readPreflight,
-      });
-      normalized.executionWalletAddress = readPreflight.executionWalletAddress || null;
-      normalized.executionWalletPreflight = readPreflight;
-      return normalized;
-    }
-    return runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, readPreflight);
-  }
+  // Market-data reads under agent_wallet must use /execute and keep the provider payload on the
+  // envelope (raw + parsed data.result). Routing them only through /execute-intent was the 0.2.34
+  // attempt to avoid a burial bug, but solo Hermes agent_wallet intents come back as an empty
+  // queued envelope with no universe. Live /execute still returns the Hyperliquid meta payload
+  // (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) {
     preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
       runMode: 'agent_wallet',
-      requireFundingCheck: true,
+      requireFundingCheck: !isRead,
       preflightSeed: options?.managedPreflight,
     });
     if (!preflight.success) {
@@ -422,33 +511,18 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
       null;
     return intentResult;
   }
-  const normalized = normalizeIntentResponse({
-    success: Boolean(response?.success),
-    status: response?.success ? 'completed' : 'failed',
-    mode: 'agent_wallet',
-    txHash: response?.txHash || null,
-    blockedReason: response?.blockedReason || response?.data?.blockedReason || null,
-    blockedStage: response?.blockedStage || response?.data?.blockedStage || null,
-    error: response?.error || null,
-    executionWalletAddress: response?.executionWalletAddress || response?.data?.executionWalletAddress || null,
-    signerMethod: 'managed_wallet_server',
-    idempotencyKey: payload.executionIdempotencyKey || null,
-    executionWalletPreflight: preflight,
-    amountNormalization: response?.amountNormalization || response?.data?.amountNormalization || null,
-    raw: response,
-  });
-  normalized.executionWalletAddress = response?.executionWalletAddress || response?.data?.executionWalletAddress || null;
-  normalized.signerMethod = 'managed_wallet_server';
-  normalized.executionWalletPreflight = preflight;
-  normalized.amountNormalization = response?.amountNormalization || response?.data?.amountNormalization || null;
-  normalized.raw = response;
-  normalized.idempotencyKey = payload.executionIdempotencyKey || null;
-  return normalized;
+  return normalizeManagedExecuteResponse(response, { preflight, payload, isRead });
 }
 
 async function executeSelfRun(ctx, flags, resolved, options) {
   const skipPreflight = Boolean(options?.skipPreflight);
   const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
+  // A read has no transaction to build or sign, so the self lane has nothing to do with it. Without
+  // this it either fails with SELF_MODE_REQUIRES_BUILD_TX or, when catalog metadata is missing, asks
+  // /build-tx to produce a transaction for a market-data query.
+  if (isReadOnlyAction(resolved)) {
+    return runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, null, options?.runMode || 'self');
+  }
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
@@ -491,6 +565,14 @@ async function executeSelfRun(ctx, flags, resolved, options) {
 
 async function executeHybridRun(ctx, flags, resolved, options) {
   const hybridWalletMode = normalizeHybridWalletMode(options?.hybridWalletMode || flags.hybridWalletMode || 'self');
+  // Reads have nothing to mirror and need no wallet, whichever hybrid wallet mode is selected.
+  // Answering from the read rail also keeps the payload at the top level, instead of nesting it under
+  // `managed` where callers that read `results` cannot find it.
+  if (isReadOnlyAction(resolved)) {
+    const readResult = await runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, null, 'hybrid');
+    readResult.hybridWalletMode = hybridWalletMode;
+    return readResult;
+  }
   if (hybridWalletMode === 'agent_wallet') {
     const managedResult = await executeManagedWalletRun(ctx, { ...flags, runMode: 'agent_wallet' }, resolved, options);
     if (!managedResult.success) {
@@ -598,15 +680,19 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     try {
       parsedRawBalance = BigInt(rawBalance);
     } catch {
-      return {
-        success: false,
-        blockedReason: 'INVALID_FUNDING_BALANCE',
-        blockedStage: 'sizing',
-        error: `Execution wallet ${executionWalletAddress || 'unknown'} returned invalid funding token balance.`,
-        executionWalletAddress,
-        signerMethod,
-        fundingTokenBalance: response?.fundingTokenBalance || null,
-      };
+      // Reads pass requireFundingCheck: false; a malformed balance must not block them.
+      // Writes still fail closed on unparseable fundingTokenBalance.raw.
+      if (options.requireFundingCheck) {
+        return {
+          success: false,
+          blockedReason: 'INVALID_FUNDING_BALANCE',
+          blockedStage: 'sizing',
+          error: `Execution wallet ${executionWalletAddress || 'unknown'} returned invalid funding token balance.`,
+          executionWalletAddress,
+          signerMethod,
+          fundingTokenBalance: response?.fundingTokenBalance || null,
+        };
+      }
     }
   }
   const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();

package/src/runtime/validation/actionParamsGate.mjs

@@ -1,4 +1,5 @@
 import { createCliError } from '../../core/envelope.mjs';
+import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import {
   sanitizeParamsForSchemaValidation,
   validateParamsSchema,
@@ -12,15 +13,7 @@ export function resolveActionParamsSchema(resolved) {
 }
 
 export function isReadOnlyCatalogAction(resolved) {
-  const meta = resolved?.resolvedActionMeta;
-  if (!meta || typeof meta !== 'object') return false;
-  const action = String(resolved?.resolvedAction || '')
-    .trim()
-    .toLowerCase()
-    .replace(/-/g, '_');
-  const readOnlyByName = action.startsWith('get_') || action.startsWith('list_') || action.startsWith('search_');
-  const readOnlyByMeta = meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
-  return readOnlyByName || readOnlyByMeta;
+  return isReadOnlyResolvedAction(resolved, { requireMeta: true });
 }
 
 export function validateResolvedActionParams(resolved, params) {

package/src/utils/cli/intentNormalization.cjs

@@ -34,7 +34,14 @@ function normalizeIntentResponse(response) {
   const topLevelDelegationSignal = String(response?.delegationSignal || '').trim() || null;
   const policyEvaluated = response?.policyEvaluated === true;
   const preflightBlocked = response?.preflightBlocked === true;
+  // This function is a whitelist, so any provider payload outside the known keys is dropped. Read
+  // actions return their data in `data` (and sometimes `raw`) rather than in `results`, so those two
+  // must survive or the caller gets a well-formed envelope with nothing in it.
+  const passthrough = {};
+  if (response?.data !== undefined) passthrough.data = response.data;
+  if (response?.raw !== undefined) passthrough.raw = response.raw;
   return {
+    ...passthrough,
     success,
     status: response?.status || (success ? 'queued' : 'failed'),
     intentId: response?.intentId || null,