@thirdfy/agent-cli 0.1.38 → 0.1.39

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.39] - 2026-05-17
+
+### Added
+
+- Framework guidance for Hermes, OpenClaw, and Claude Managed Agents in `help onboarding`, README, and command reference so agents can choose CLI/MCP rails correctly.
+- Gator-style `delegation grant` alias and clearer external-wallet delegation next steps.
+
+### Changed
+
+- Fresh solo profiles now default to `agent_wallet`, persist/resolve owner `userDid`, and use owner-matched mirror scope for hybrid validation.
+
 ## [0.1.38] - 2026-05-17
 
 ### Fixed

package/README.md

@@ -9,12 +9,13 @@ Use it to:
 - run governance preflight checks
 - queue execute-intent requests with idempotency
 - poll intent status with stable JSON output for automation
-- choose execution topology with one switch: `thirdfy`, `self`, or `hybrid`
+- choose execution topology with one switch: `agent_wallet`, `self`, `hybrid`, or `thirdfy`
 - configure profile-driven defaults (`personal`, `builder`, `network`)
 
 If you want the full developer docs, start here:
-- [Thirdfy Agent CLI docs](https://docs.thirdfy.com/api/thirdfy-agent-cli)
-- [API Reference home](https://docs.thirdfy.com/api)
+- [Thirdfy Agent CLI hub](https://docs.thirdfy.com/documentation/agent-cli) (guided chapters)
+- [Thirdfy Agent CLI — full reference](https://docs.thirdfy.com/documentation/api/thirdfy-agent-cli)
+- [API Reference home](https://docs.thirdfy.com/documentation/api/api-reference)
 - [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
 - [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
 - [Provider docs index (repo)](./docs/providers/index.md)
@@ -41,7 +42,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. **v0.1.35** extended `thirdfy-agent actions` hints for Polymarket Gamma-style discovery (`gamma_search_*` where catalog-backed) and legacy `search_polymarket` / `get_polymarket_*` reads, with public docs aligned to the deposit-wallet (pUSD / POLY_1271) operator path. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
+Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.1.39** makes `agent_wallet` the fresh solo default, adds framework guidance for Hermes/OpenClaw/Claude Managed Agents, clarifies Gator/ERC-7710 delegation flows, and keeps BYOW/self plus hybrid/thirdfy mode switching explicit. **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
 
 **Maintainers — npm:** follow [docs/releasing.md](./docs/releasing.md). From a clone with gitignored `.env`, use `npm run publish:npm:local -- --dry-run` then `npm run publish:npm:local`. Or run `npm run release:npm` after exporting tokens in the shell. Never commit npm tokens — use [.env.example](./.env.example) as a template only.
 
@@ -103,7 +104,7 @@ thirdfy-agent logout --json
 thirdfy-agent logout --all --json
 ```
 
-`login email` is a two-step headless-safe flow. Without `--code`, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With `--code --accept-terms`, it stores a short-lived owner session in `~/.thirdfy/config.json`, records linked EVM/Solana wallets when Privy returns them, and stores a new agent API key when first-run bootstrap issues one. Use `--not-interactive` / `--ni` in automation so missing input fails fast instead of prompting — place **`--ni` after the `login email` subcommand** (for example `thirdfy-agent login email you@example.com --code … --accept-terms --ni`); a leading `thirdfy-agent --ni login email …` is parsed incorrectly because `--ni` would consume the `login` token as its value.
+`login email` is a two-step headless-safe flow. Without `--code`, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With `--code --accept-terms`, it stores a short-lived owner session in `~/.thirdfy/config.json`, records linked EVM/Solana wallets plus the owner `userDid` when Privy returns them, stores a new agent API key when first-run bootstrap issues one, and defaults new solo profiles to `agent_wallet`. Use `--not-interactive` / `--ni` in automation so missing input fails fast instead of prompting — place **`--ni` after the `login email` subcommand** (for example `thirdfy-agent login email you@example.com --code … --accept-terms --ni`); a leading `thirdfy-agent --ni login email …` is parsed incorrectly because `--ni` would consume the `login` token as its value.
 
 `logout --all` is provider-agnostic: it attempts owner-session revocation when a session token exists, then always clears local credentials.
 
@@ -149,15 +150,17 @@ thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --challenge-id "
 
 `thirdfy-agent` supports one command surface with four run modes:
 
-- `--run-mode thirdfy` -> Thirdfy-governed execute-intent rail (default for `profile=network`)
-- `--run-mode self` -> self-custody rail (`build-tx` flow; default for `profile=personal`)
+- `--run-mode agent_wallet` -> managed solo wallet execution rail and fresh email-login default
+- `--run-mode self` -> self-custody rail (`build-tx` flow)
 - `--run-mode hybrid` -> self-custody + governance mirror metadata (default for `profile=builder`)
-- `--run-mode agent_wallet` -> managed wallet execution rail for Claude-friendly hosted execution
+- `--run-mode thirdfy` -> Thirdfy-governed execute-intent rail (default for `profile=network`)
 
 | Goal | Recommended mode | Why |
 | --- | --- | --- |
+| Fast solo managed-wallet trading | `agent_wallet` | Uses `/execution-wallet` + `/execute`; owner `userDid` comes from login config. |
 | BYOW signing and local custody | `self` | Keeps signing and broadcast on your wallet path. |
-| Managed delegated execution | `thirdfy` | Uses delegated governance rail for hosted execution. |
+| External wallet delegated execution | `hybrid` or `thirdfy` after `delegation create/activate` | Uses Gator/ERC-7710 authority from the user wallet to the Thirdfy/session executor. |
+| Publisher fan-out / subscriber execution | `thirdfy` | Uses delegated governance rail and active `delegation_bindings`. |
 | Self execution plus governance mirror checks | `hybrid` | Preserves local execution while emitting managed-lane mirrors. |
 | Managed wallet primary + governance mirror checks | `hybrid --hybrid-wallet-mode agent_wallet` | Uses managed wallet as primary hybrid path while still running Thirdfy mirror checks. |
 
@@ -166,7 +169,7 @@ Auth expectations by mode:
 - `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
 - `hybrid`: requires execution identity and governed mirror semantics (`--hybrid-wallet-mode self|agent_wallet`, default `self`).
 - `thirdfy`: requires execution identity and delegated governance path.
-- `agent_wallet`: requires execution identity and delegated managed-wallet path.
+- `agent_wallet`: requires execution identity and owner `userDid`, but does not require subscriber delegation when the owner identity matches the agent wallet/creator.
 - custody mode defaults are profile-aware:
   - `managed` default for `thirdfy`
   - `external` default for `self` and `hybrid`
@@ -177,7 +180,7 @@ Selection precedence:
 1. `--run-mode`
 2. `THIRDFY_RUN_MODE`
 3. saved profile config (`~/.thirdfy/config.json`)
-4. profile default
+4. profile default (`personal=agent_wallet`, `builder=hybrid`, `network=thirdfy`)
 
 Profile commands:
 
@@ -189,6 +192,16 @@ thirdfy-agent whoami --json
 
 `profile use --profile <name>` resets run mode to that profile default unless `--run-mode` is explicitly provided.
 
+## Framework Guidance
+
+Use the same execution identities across frameworks, but choose the rail by who signs and who the agent acts for:
+
+- **Hermes agents:** provision the Thirdfy profile and env before the Hermes dashboard/runtime starts, run `thirdfy-agent doctor auth` and `doctor self` during startup checks, prefer `agent_wallet` for the agent’s own managed wallet, and keep `thirdfy` for publisher/fanout or delegated external-wallet execution.
+- **OpenClaw agents:** store Thirdfy credentials as runtime secrets, call `thirdfy-agent actions --provider <id>` before planning, use `run --run-mode agent_wallet` for own-wallet actions, use `self` only when OWS/local signing is configured, and switch to `hybrid`/`thirdfy` only after delegation readiness is confirmed.
+- **Claude Managed Agents:** prefer MCP `agentRun` / `walletExecute` for solo managed execution, `buildTx` / `walletSign` for BYOW local signing, and `executeIntent` only for subscriber fanout or explicit validation-only mirror previews. The CLI remains useful for smoke checks and local operator recovery.
+
+For all frameworks, treat `agentApiKey` as a hidden execution credential in secret storage, keep owner-session tokens short lived, and verify mode requirements with `thirdfy-agent help onboarding --json`.
+
 ### One-command self execution (BYOW)
 
 Use `--broadcast` with `run --run-mode self` to keep one deterministic command for build/sign/send:
@@ -400,7 +413,7 @@ Managed-self execution performs strict wallet preflight and returns deterministi
 ## More docs
 
 - OpenClaw CLI onboarding flow:
-  [docs.thirdfy.com/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli](https://docs.thirdfy.com/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli)
+  [docs.thirdfy.com/documentation/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli](https://docs.thirdfy.com/documentation/api/thirdfy-agent-cli#create-an-openclaw-agent-with-the-cli)
 - Creator platform (agent registration and keys):
   [thirdfy.com/creator](https://thirdfy.com/creator)
 
@@ -416,7 +429,7 @@ npm run e2e:managed:delegation:parity
 
 ## Release
 
-Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [v0.1.38](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.38) — npm README + lockfile metadata alignment; [v0.1.37](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.37) — email OTP login, onboarding help, auth doctor, wallet list, masked `whoami`). **Before every version bump or npm publish:** update this **README** (release notes paragraph, quick start, and command groups) so the npm package page matches what ships; keep `CHANGELOG.md`, [command reference](./docs/command-reference.md), and MCP summaries aligned when discovery or onboarding surfaces change.
+Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [v0.1.39](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.39) — agent-wallet solo default, framework guidance, and delegation UX; [v0.1.38](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.38) — npm README + lockfile metadata alignment; [v0.1.37](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.37) — email OTP login, onboarding help, auth doctor, wallet list, masked `whoami`). **Before every version bump or npm publish:** update this **README** (release notes paragraph, quick start, and command groups) so the npm package page matches what ships; keep `CHANGELOG.md`, [command reference](./docs/command-reference.md), and MCP summaries aligned when discovery or onboarding surfaces change.
 
 ```bash
 npm version patch

package/bin/thirdfy-agent.mjs

@@ -43,7 +43,7 @@ const CUSTODY_MODES = ['managed', 'external'];
 const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
 let negotiatedCapabilitiesCache = null;
 const PROFILE_DEFAULTS = {
-  personal: 'self',
+  personal: 'agent_wallet',
   builder: 'hybrid',
   network: 'thirdfy',
 };
@@ -224,6 +224,7 @@ async function main() {
       await commandTrackAction(context, subFlags, capabilities);
       return;
     case 'delegation create':
+    case 'delegation grant':
       await commandDelegationCreate(context, subFlags, capabilities);
       return;
     case 'delegation init-custodial':
@@ -1432,7 +1433,17 @@ async function commandDelegationCreate(ctx, flags, capabilities) {
     success,
     code: success ? 'DELEGATION_CREATED' : 'DELEGATION_CREATE_FAILED',
     message: response?.message || (success ? 'Delegation payload created' : 'Delegation create failed'),
-    data: response,
+    data: {
+      ...response,
+      delegationModel: 'gator_erc7710',
+      nextSteps: success
+        ? [
+            'Sign data.delegation with the external wallet or OWS account that owns --owner-address.',
+            'Run `thirdfy-agent delegation activate --agent-key <key> --wallet-address <owner> --session-account-address <delegate> --delegation-manager <manager> --delegation <json> --signature <hex>`.',
+            'Verify with `thirdfy-agent delegation inspect --agent-key <key> --verify`, then use `delegation redeem` or run with --run-mode hybrid|thirdfy for delegated execution.',
+          ]
+        : [],
+    },
     meta: {
       apiBase: ctx.apiBase,
       capabilitiesVersion: capabilities?.contractVersion || null,
@@ -1533,7 +1544,16 @@ async function commandDelegationActivate(ctx, flags, capabilities) {
     success,
     code: success ? 'DELEGATION_ACTIVATED' : 'DELEGATION_ACTIVATE_FAILED',
     message: response?.message || (success ? 'Delegation activated' : 'Delegation activate failed'),
-    data: response,
+    data: {
+      ...response,
+      delegationModel: 'gator_erc7710',
+      nextSteps: success
+        ? [
+            'Run `thirdfy-agent delegation inspect --agent-key <key> --verify` to confirm period allowance and revocation state.',
+            'Use `thirdfy-agent delegation redeem --run-mode hybrid|thirdfy ...` when Thirdfy/session executor should act under this external-wallet delegation.',
+          ]
+        : [],
+    },
     meta: {
       apiBase: ctx.apiBase,
       capabilitiesVersion: capabilities?.contractVersion || null,
@@ -2434,8 +2454,8 @@ async function commandProfileShow(ctx, _flags) {
     message: 'Profile configuration loaded',
     data: {
       profile: ctx.profile || config.profile || 'personal',
-      runMode: ctx.runMode || config.runMode || 'thirdfy',
-      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'thirdfy'),
+      runMode: ctx.runMode || config.runMode || 'agent_wallet',
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'agent_wallet'),
       profileDefaults: PROFILE_DEFAULTS,
       configPath: getProfileConfigPath(),
       config,
@@ -2455,7 +2475,7 @@ function maskSecret(value) {
 function buildOnboardingHelp(ctx) {
   return {
     title: 'Thirdfy Agent CLI onboarding',
-    summary: 'Use email OTP, wallet-sign, or existing credentials to create owner auth, wallets, and agent execution credentials.',
+    summary: 'Use email OTP, wallet-sign, or existing credentials to create owner auth, wallets, and hidden agent execution credentials. Fresh solo profiles default to agent_wallet.',
     paths: [
       {
         id: 'email_otp',
@@ -2466,6 +2486,7 @@ function buildOnboardingHelp(ctx) {
           'thirdfy-agent login email user@example.com --code <otp> --accept-terms --key-name "My Agent"',
           'thirdfy-agent whoami',
           'thirdfy-agent managed wallet init --chain-id 8453',
+          'thirdfy-agent preflight --run-mode agent_wallet --action <action> --params <json> --json',
         ],
       },
       {
@@ -2499,6 +2520,21 @@ function buildOnboardingHelp(ctx) {
         'thirdfy-agent login email user@example.com --code 123456 --accept-terms --ni (place --ni after the subcommand so it is not parsed as a flag value)',
       rule: 'Commands must fail fast instead of waiting for prompts when required input is missing.',
     },
+    executionModes: {
+      agent_wallet: 'Solo managed wallet execution through /execution-wallet + /execute; no subscriber binding when owner userDid matches.',
+      self: 'BYOW/OWS local signing through build-tx, wallet sign, and wallet submit.',
+      hybrid: 'Primary self or agent_wallet execution with optional Thirdfy mirror validation.',
+      thirdfy: 'Publisher/fanout execute-intent; requires active subscriber/delegation bindings for writes.',
+      externalDelegation: 'Use delegation create/grant -> sign -> activate -> inspect/balance -> redeem for Gator/ERC-7710 external-wallet authority.',
+    },
+    frameworkGuidance: {
+      hermes:
+        'Hermes agents should receive a pre-provisioned Thirdfy profile/env, run doctor auth/self at startup, use agent_wallet for managed solo writes, and keep strategy logic separate from CLI secrets.',
+      openclaw:
+        'OpenClaw agents should keep Thirdfy credentials in runtime secrets, use actions discovery before planning, prefer run --run-mode agent_wallet for own-wallet execution, and use thirdfy only for publisher/fanout.',
+      claudeManagedAgents:
+        'Claude Managed Agents should use MCP agentRun/walletExecute for solo managed execution, walletSign/buildTx for BYOW, and executeIntent only for fanout or mirror previews.',
+    },
     apiBase: ctx.apiBase,
   };
 }
@@ -2518,14 +2554,15 @@ async function commandWhoami(ctx, _flags) {
   const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
   const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
   const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  const runMode = ctx.runMode || config.runMode || 'agent_wallet';
   printEnvelope({
     success: true,
     code: 'WHOAMI_OK',
     message: 'Thirdfy CLI identity loaded',
     data: {
       profile: ctx.profile || config.profile || 'personal',
-      runMode: ctx.runMode || config.runMode || 'thirdfy',
-      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'thirdfy'),
+      runMode,
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(runMode),
       auth: {
         source: auth.source || null,
         hasAuthToken: Boolean(auth.authToken),
@@ -2539,6 +2576,7 @@ async function commandWhoami(ctx, _flags) {
         agentKey: agent.agentKey || null,
       },
       wallets: {
+        userDid: wallets.userDid || config.identity?.userDid || null,
         primaryEvmWallet: wallets.primaryEvmWallet || null,
         evm: Array.isArray(wallets.evm) ? wallets.evm : [],
         solana: Array.isArray(wallets.solana) ? wallets.solana : [],
@@ -2571,6 +2609,8 @@ async function commandDoctorAuth(ctx, _flags) {
   const config = loadProfileConfig();
   const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
   const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
+  const runMode = normalizeRunMode(ctx.runMode || config.runMode || 'agent_wallet');
+  const userDid = resolveEffectiveUserDid({});
   const ownerSessionTokenFromEnv = String(process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
   const authTokenFromEnv = String(process.env.THIRDFY_AUTH_TOKEN || '').trim();
   const agentApiKeyFromEnv = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
@@ -2598,6 +2638,14 @@ async function commandDoctorAuth(ctx, _flags) {
           ? 'agent API key from THIRDFY_AGENT_API_KEY'
           : 'not stored yet (optional until execution); complete onboarding or bootstrap to add one',
     },
+    {
+      name: 'user-did',
+      optional: runMode !== 'agent_wallet',
+      ok: Boolean(userDid),
+      detail: userDid
+        ? `user DID available (${userDid})`
+        : 'missing user DID; run `thirdfy-agent login email <email>` or set THIRDFY_USER_DID',
+    },
     {
       name: 'wallet-profile',
       ok: Boolean(config.wallets?.primaryEvmWallet || (Array.isArray(config.wallets?.evm) && config.wallets.evm.length)),
@@ -2660,7 +2708,7 @@ async function commandLogin(ctx, flags) {
   const current = loadProfileConfig();
   const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
   let ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
-  const loginRunMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy');
+  const loginRunMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet');
   const custodyMode = normalizeCustodyMode(
     flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
     loginRunMode
@@ -2842,10 +2890,10 @@ async function commandLoginEmail(ctx, flags) {
     acceptTerms: true,
     keyName,
     agentKey: String(flags.agentKey || '').trim() || undefined,
-    runMode: normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy'),
+    runMode: normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet'),
     custodyMode: normalizeCustodyMode(
       flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
-      normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy')
+      normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet')
     ),
     bootstrapAgent: !parseBooleanFlag(flags.noBootstrapAgent, false),
     rotateAgentKey: parseBooleanFlag(flags.rotateAgentKey, false),
@@ -2856,12 +2904,14 @@ async function commandLoginEmail(ctx, flags) {
   const agentApiKey = String(bootstrap.agentApiKey || '').trim();
   const agentKey = String(bootstrap.agentKey || data.owner?.creatorWallet || '').trim();
   const wallets = data.wallets && typeof data.wallets === 'object' ? data.wallets : {};
+  const userDid = String(data.owner?.creatorDid || wallets.userDid || '').trim();
   const primaryEvmWallet = String(wallets.primaryEvmWallet || data.owner?.creatorWallet || '').trim();
   const persistedWallets = {
     ...wallets,
+    ...(userDid ? { userDid } : {}),
     ...(primaryEvmWallet ? { primaryEvmWallet } : {}),
   };
-  const runMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'thirdfy');
+  const runMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet');
   const custodyMode = normalizeCustodyMode(flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE, runMode);
   if (!ownerSessionToken) {
     throw createCliError('LOGIN_EMAIL_OWNER_SESSION_MISSING', 'Email onboarding completed without an owner session token.');
@@ -3590,6 +3640,15 @@ function buildBuildTxPayload(flags, resolvedAction) {
   return payload;
 }
 
+function resolveEffectiveUserDid(flags) {
+  const explicit = String(flags.userDid || '').trim();
+  if (explicit) return explicit;
+  const envUserDid = String(process.env.THIRDFY_USER_DID || '').trim();
+  if (envUserDid) return envUserDid;
+  const config = loadProfileConfig();
+  return String(config?.wallets?.userDid || config?.identity?.userDid || '').trim();
+}
+
 function buildManagedExecutePayload(flags, options) {
   const runMode = String(options.runMode || flags.runMode || 'agent_wallet').trim().toLowerCase();
   const params = getPreparedParams(flags);
@@ -3620,7 +3679,7 @@ function buildManagedExecutePayload(flags, options) {
   const payload = {
     agentApiKey: resolveAgentApiKey(flags, runMode),
     action: String(options.resolvedAction || requireFlag(flags, 'action', 'Missing --action')).trim(),
-    userDid: String(flags.userDid || process.env.THIRDFY_USER_DID || '').trim(),
+    userDid: resolveEffectiveUserDid(flags),
     params: managedParams,
     chainId: Number(flags.chainId || 8453),
     executionStrategy: {
@@ -3631,7 +3690,7 @@ function buildManagedExecutePayload(flags, options) {
   if (!payload.userDid) {
     throw createCliError(
       'MISSING_USER_DID',
-      'Managed wallet execution requires --user-did (or THIRDFY_USER_DID).'
+      'Managed wallet execution requires --user-did, THIRDFY_USER_DID, or a saved userDid from `thirdfy-agent login email`.'
     );
   }
   if (flags.estimatedAmountUsd) payload.estimatedAmountUsd = Number(flags.estimatedAmountUsd);
@@ -3655,13 +3714,13 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
   const chainId = Number(flags.chainId || 8453);
   const runMode = String(options.runMode || 'agent_wallet').trim().toLowerCase();
   const agentApiKey = resolveAgentApiKey(flags, runMode);
-  const userDid = String(flags.userDid || process.env.THIRDFY_USER_DID || '').trim();
+  const userDid = resolveEffectiveUserDid(flags);
   if (!userDid) {
     return {
       success: false,
       blockedReason: 'MISSING_USER_DID',
       blockedStage: 'routing',
-      error: 'Managed wallet execution requires --user-did (or THIRDFY_USER_DID).',
+      error: 'Managed wallet execution requires --user-did, THIRDFY_USER_DID, or a saved userDid from `thirdfy-agent login email`.',
       signerMethod: 'managed_wallet_server',
     };
   }
@@ -3742,8 +3801,16 @@ function buildIntentPayload(flags, options) {
   if (flags.catalog) payload.catalog = String(flags.catalog).trim();
   if (flags.chainId) payload.chainId = Number(flags.chainId);
   if (flags.estimatedAmountUsd) payload.estimatedAmountUsd = Number(flags.estimatedAmountUsd);
-  if (flags.userDid) payload.userDid = String(flags.userDid);
+  const userDid = resolveEffectiveUserDid(flags);
+  if (flags.userDid || (options.validationOnly && (runMode === 'agent_wallet' || (runMode === 'hybrid' && options.mirrorOnly)))) {
+    if (userDid) payload.userDid = userDid;
+  }
   if (options.validationOnly) payload.executionLane = 'validation_only';
+  if (flags.executionScope) {
+    payload.executionScope = String(flags.executionScope).trim();
+  } else if (options.validationOnly && (runMode === 'agent_wallet' || (runMode === 'hybrid' && options.mirrorOnly))) {
+    payload.executionScope = 'solo_owner_mirror';
+  }
   if (options.runMode) {
     payload.executionStrategy = {
       runMode: String(options.runMode),

package/package.json

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