@phnx-labs/agents-cli 1.22.22 → 1.22.23

package/dist/lib/agents.js

@@ -751,6 +751,66 @@ export const AGENTS = {
             interactiveRepl: true,
         },
     },
+    // Meta Muse Code (`muse`) — first-class harness for Meta's coding agent (terminal/CI), built on
+    // Muse Spark. Native binary via curl installer (self-updating; no npm package).
+    // Config: `~/.config/muse/settings.json` (requires `"schema_version": 1`).
+    // Sessions: `~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl`.
+    // Skills: `~/.config/muse/skills` + `~/.agents/skills` + project `.agents/skills`.
+    // MCP: `mcp_servers` in settings.json (stdio / streamable_http transports).
+    // Headless: `muse exec "<prompt>"` with --model, --reasoning-effort, --json,
+    // --yolo / --disable-approval / --disable-sandbox. Auth: META_API_KEY or
+    // browser OAuth stored at `~/.config/muse/auth.json`. Default model:
+    // muse-spark-1.2. Docs: https://dev.meta.ai/docs/muse-code
+    muse: {
+        id: 'muse',
+        name: 'Muse',
+        color: 'blueBright',
+        cliCommand: 'muse',
+        npmPackage: '',
+        installScript: 'curl -fsSL https://dev.meta.ai/install.sh | sh',
+        configDir: path.join(HOME, '.config', 'muse'),
+        authFiles: ['auth.json'],
+        commandsDir: '',
+        commandsSubdir: '',
+        skillsDir: path.join(HOME, '.config', 'muse', 'skills'),
+        hooksDir: 'hooks',
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        // Muse hooks use the Claude-shaped settings.json hooks block (matcher +
+        // command groups) under ~/.config/muse/settings.json, plus project
+        // `.muse/hooks.json`. registerHooksForClaude is reused with Muse's config
+        // dir and schema_version: 1.
+        supportsHooks: true,
+        // Claude-compatible marketplace layout + native `.muse-plugin/` manifest.
+        pluginManifestDir: '.muse-plugin',
+        capabilities: {
+            // Hooks: Claude-compatible event→matcher→command groups in settings.json.
+            hooks: true,
+            mcp: true,
+            mcpHttp: true,
+            mcpHeaders: true,
+            // Muse's safety model is approval-mode + OS sandbox (CLI flags), not a
+            // Claude-style tool-name allow/deny list. No settings.permissions writer.
+            allowlist: false,
+            skills: true,
+            // No slash-command file dir; skills double as reusable workflows.
+            commands: false,
+            // Plugins: Claude marketplace + .muse-plugin (syncPluginToVersion).
+            plugins: true,
+            // Runtime multi-agent / subagents exist, but there is no installable
+            // subagent-definition directory for agents-cli to sync into (capability
+            // table must stay truthful — see subagents-registry completeness).
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            // Portable memory at <repo>/.agents/memory/ + personal scopes.
+            memory: true,
+            modes: ['plan', 'edit', 'auto', 'skip'],
+            rulesImports: false,
+            interactiveRepl: true,
+        },
+    },
 };
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
@@ -965,6 +1025,7 @@ export const UNMANAGED_DETECTION_CANDIDATES = [
     'grok',
     'copilot',
     'droid',
+    'muse',
 ];
 /**
  * Detect existing agent installations that are NOT yet managed by agents-cli.
@@ -1071,6 +1132,7 @@ export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'kimi',
     'droid',
     'opencode',
+    'muse',
 ];
 const ACCOUNT_INSPECTION_AGENTS = new Set(ACCOUNT_INSPECTION_AGENT_IDS);
 /** Whether agents-cli can determine this agent's per-version sign-in state. */
@@ -1150,6 +1212,9 @@ const CREDENTIAL_FILE_SEGMENTS = {
     droid: [['.factory', 'auth.v2.file']],
     antigravity: [['.gemini', 'antigravity-cli', 'antigravity-oauth-token']],
     opencode: [['.local', 'share', 'opencode', 'auth.json']],
+    // Muse Code stores OAuth / API credentials at ~/.config/muse/auth.json
+    // (or META_API_KEY in the environment, which is not a file).
+    muse: [['.config', 'muse', 'auth.json']],
 };
 /** Whether an agent's credential file exists under a given home. */
 function credentialFileExistsUnder(agentId, home) {
@@ -1440,6 +1505,31 @@ function isValidOpenCodeCredential(value) {
         default: return false;
     }
 }
+/**
+ * Whether a Muse Code `~/.config/muse/auth.json` document holds any usable
+ * access token. The launcher stores per-provider slots (e.g. `meta`) each with
+ * an `access_token` string; a top-level `access_token` is also accepted.
+ * Never returns the secret itself — presence only.
+ */
+function museAuthHasToken(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const root = value;
+    if (typeof root.access_token === 'string' && root.access_token.length > 0)
+        return true;
+    if (typeof root.api_key === 'string' && root.api_key.length > 0)
+        return true;
+    for (const slot of Object.values(root)) {
+        if (!slot || typeof slot !== 'object' || Array.isArray(slot))
+            continue;
+        const entry = slot;
+        if (typeof entry.access_token === 'string' && entry.access_token.length > 0)
+            return true;
+        if (typeof entry.api_key === 'string' && entry.api_key.length > 0)
+            return true;
+    }
+    return false;
+}
 /**
  * Whether a Claude version home's credential file is present but carries no
  * token — the "must have a real credential" floor (see
@@ -1832,6 +1922,30 @@ export async function getAccountInfo(agentId, home) {
                 const accountKey = buildIdentityKey(agentId, [['providers', accountId]]);
                 return { ...empty, signedIn: true, accountId, accountKey, lastActive };
             }
+            case 'muse': {
+                // Muse Code authenticates with META_API_KEY (env, highest priority) or
+                // a stored OAuth/API credential at ~/.config/muse/auth.json. The auth
+                // file is launcher-managed JSON with per-provider slots holding
+                // access_token; there is no email claim, so we report signed-in + a
+                // stable identity key (env-key vs provider slots) like kimi/opencode.
+                if (process.env.META_API_KEY?.trim() || process.env.MODEL_API_KEY?.trim()) {
+                    const accountKey = buildIdentityKey(agentId, [['auth', 'env']]);
+                    return { ...empty, signedIn: true, accountId: 'env', accountKey, lastActive };
+                }
+                const authPath = resolveAccountCredentialPath(base, '.config', 'muse', 'auth.json');
+                if (!authPath)
+                    return { ...empty, lastActive };
+                const data = JSON.parse(await fs.promises.readFile(authPath, 'utf-8'));
+                if (!data || typeof data !== 'object')
+                    return { ...empty, lastActive };
+                // auth.json shape: { meta?: { access_token }, … } or similar slots.
+                // Any object with a nested access_token (or a top-level one) counts.
+                const hasToken = museAuthHasToken(data);
+                if (!hasToken)
+                    return { ...empty, lastActive };
+                const accountKey = buildIdentityKey(agentId, [['auth', 'file']]);
+                return { ...empty, signedIn: true, accountId: 'file', accountKey, lastActive };
+            }
             default:
                 return { ...empty, lastActive };
         }
@@ -1935,6 +2049,10 @@ function getSessionDir(agentId, base) {
             return path.join(base, '.copilot', 'session-state');
         case 'droid':
             return path.join(base, '.factory', 'sessions');
+        case 'muse':
+            // Muse sessions live under XDG data, not the config dir:
+            // ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
+            return path.join(base, '.local', 'share', 'muse', 'sessions');
         default:
             return null;
     }
@@ -1946,6 +2064,7 @@ function getSessionExtension(agentId) {
         case 'codex':
         case 'copilot':
         case 'droid':
+        case 'muse':
             return '.jsonl';
         case 'gemini':
             return '.json';
@@ -2441,6 +2560,9 @@ export function getUserMcpConfigPath(agentId) {
         case 'pi':
             // omp reads user-scope MCP from ~/.omp/agent/.mcp.json (Claude schema).
             return path.join(agent.configDir, '.mcp.json');
+        case 'muse':
+            // Muse Code: MCP lives in ~/.config/muse/settings.json under mcp_servers.
+            return path.join(agent.configDir, 'settings.json');
         default:
             // Gemini and others use settings.json
             return path.join(agent.configDir, 'settings.json');
@@ -2479,6 +2601,8 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.hermes', 'config.yaml');
         case 'pi':
             return path.join(home, '.omp', 'agent', '.mcp.json');
+        case 'muse':
+            return path.join(home, '.config', 'muse', 'settings.json');
         default:
             return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
@@ -2521,6 +2645,10 @@ export function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
         case 'pi':
             // omp reads project MCP from <root>/.mcp.json (Claude-compatible).
             return path.join(cwd, '.mcp.json');
+        case 'muse':
+            // Muse project MCP rides the same settings schema under .muse/settings.json
+            // when present; otherwise fall back to the user settings path.
+            return path.join(cwd, '.muse', 'settings.json');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }
@@ -2664,6 +2792,10 @@ export const AGENT_NAME_ALIASES = {
     droid: 'droid',
     hermes: 'hermes',
     'hermes-agent': 'hermes',
+    muse: 'muse',
+    'muse-code': 'muse',
+    'muse-spark': 'muse',
+    'meta-muse': 'muse',
 };
 /**
  * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.

package/dist/lib/codex-policy.d.ts

@@ -0,0 +1,17 @@
+export type CodexPolicyMode = 'plan' | 'edit' | 'skip';
+export declare const CODEX_PLAN_PROFILE = "agents-plan";
+export declare const CODEX_EDIT_PROFILE = "agents-edit";
+export declare function codexEditWritableRoots(): string[];
+export declare function codexPermissionProfileConfig(mode: Exclude<CodexPolicyMode, 'skip'>, writableRoots?: string[]): string;
+/**
+ * Canonical Codex safety policy used by every native launch path.
+ *
+ * Config overrides are deliberately used instead of the legacy `--sandbox`
+ * flags: named permission profiles are the only Codex surface that can keep a
+ * plan run filesystem-read-only while independently enabling network access.
+ */
+export declare function codexPolicyArgs(mode: CodexPolicyMode, writableRoots?: string[]): string[];
+/** Preserve whether --mode was omitted when a run is re-dispatched remotely. */
+export declare function modeForRemoteDispatch(mode: string, source: string | undefined): string | undefined;
+/** Only the untouched Commander default selects Codex's writable default. */
+export declare function modeWasImplicit(source: string | undefined, hasConfiguredDefault: boolean): boolean;

package/dist/lib/codex-policy.js

@@ -0,0 +1,48 @@
+import { getUserAgentsDir } from './state.js';
+import { codexDefaultWritableRoots } from './permissions.js';
+export const CODEX_PLAN_PROFILE = 'agents-plan';
+export const CODEX_EDIT_PROFILE = 'agents-edit';
+function unique(values) {
+    return [...new Set(values)];
+}
+export function codexEditWritableRoots() {
+    return unique([getUserAgentsDir(), ...codexDefaultWritableRoots()]);
+}
+function inlineWorkspaceRoots(roots) {
+    return roots.map((root) => `${JSON.stringify(root)} = true`).join(', ');
+}
+export function codexPermissionProfileConfig(mode, writableRoots = codexEditWritableRoots()) {
+    const parent = mode === 'plan' ? ':read-only' : ':workspace';
+    const roots = mode === 'edit'
+        ? `, workspace_roots = { ${inlineWorkspaceRoots(unique(writableRoots))} }`
+        : '';
+    return `{ extends = ${JSON.stringify(parent)}${roots}, network = { enabled = true, allow_local_binding = true } }`;
+}
+/**
+ * Canonical Codex safety policy used by every native launch path.
+ *
+ * Config overrides are deliberately used instead of the legacy `--sandbox`
+ * flags: named permission profiles are the only Codex surface that can keep a
+ * plan run filesystem-read-only while independently enabling network access.
+ */
+export function codexPolicyArgs(mode, writableRoots = codexEditWritableRoots()) {
+    if (mode === 'skip')
+        return ['--dangerously-bypass-approvals-and-sandbox'];
+    const profile = mode === 'plan' ? CODEX_PLAN_PROFILE : CODEX_EDIT_PROFILE;
+    return [
+        '-c',
+        'approval_policy="on-request"',
+        '-c',
+        `default_permissions=${JSON.stringify(profile)}`,
+        '-c',
+        `permissions.${profile}=${codexPermissionProfileConfig(mode, writableRoots)}`,
+    ];
+}
+/** Preserve whether --mode was omitted when a run is re-dispatched remotely. */
+export function modeForRemoteDispatch(mode, source) {
+    return source === 'default' ? undefined : mode;
+}
+/** Only the untouched Commander default selects Codex's writable default. */
+export function modeWasImplicit(source, hasConfiguredDefault) {
+    return source === 'default' && !hasConfiguredDefault;
+}

package/dist/lib/crabbox/lease.d.ts

@@ -118,4 +118,29 @@ export interface LeaseRunResult {
  * the credential files. Best-effort install steps never abort the run.
  */
 export declare function buildBootstrapScript(opts: LeaseRunOptions): string;
+/** Untouched-for-this-long ⇒ no active run holds the box, so an expired one is a stray. */
+export declare const STRAY_GRACE_SECS = 600;
+export interface StrayMatchOptions {
+    /** Pool the lease belongs to (defaults to DEFAULT_CRABBOX_PROFILE). */
+    profile?: string;
+    /** Network mode of the lease (default 'public'); a box is partitioned by it. */
+    netMode?: 'public' | 'tailscale';
+    /** The box this run is using — never a stray. */
+    keepSlug: string;
+    /** Injectable clock (unix seconds). */
+    nowSecs?: number;
+    /** Idle grace window (defaults to {@link STRAY_GRACE_SECS}). */
+    graceSecs?: number;
+}
+/**
+ * Whether `box` is an EXPIRED, idle stray in this run's pool — the boxes that
+ * accumulate cost. An expired box can never be reused (`poolReusableBoxes` gates
+ * on an unexpired lease), yet `keep:true` leaves it running, so without a sweep a
+ * fresh provision leaves the old one billing until `gc`'s 1h-idle window. Only a
+ * box that is running, in the SAME profile+netMode pool, has an EXPIRED lease, and
+ * has been untouched for the grace window is a stray — a mid-boot or in-use box
+ * (recent `lastTouchedAt`, or an unexpired lease) is never one. Pure — testable
+ * without a shell.
+ */
+export declare function isExpiredPoolStray(box: CrabboxBox, opts: StrayMatchOptions): boolean;
 export declare function leaseAndRun(opts: LeaseRunOptions): Promise<LeaseRunResult>;

package/dist/lib/crabbox/lease.js

@@ -33,6 +33,7 @@ import * as yaml from 'yaml';
 import { buildCredentialScript, buildHomeFileWriteScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
 import { copySetupToBox } from './setup-copy.js';
+import { DEFAULT_CRABBOX_PROFILE } from './config.js';
 /** POSIX single-quote for safe embedding in the generated bootstrap script. */
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
@@ -173,6 +174,60 @@ function pickReadyPoolBox(opts) {
     }
     return null;
 }
+/** Untouched-for-this-long ⇒ no active run holds the box, so an expired one is a stray. */
+export const STRAY_GRACE_SECS = 600;
+/**
+ * Whether `box` is an EXPIRED, idle stray in this run's pool — the boxes that
+ * accumulate cost. An expired box can never be reused (`poolReusableBoxes` gates
+ * on an unexpired lease), yet `keep:true` leaves it running, so without a sweep a
+ * fresh provision leaves the old one billing until `gc`'s 1h-idle window. Only a
+ * box that is running, in the SAME profile+netMode pool, has an EXPIRED lease, and
+ * has been untouched for the grace window is a stray — a mid-boot or in-use box
+ * (recent `lastTouchedAt`, or an unexpired lease) is never one. Pure — testable
+ * without a shell.
+ */
+export function isExpiredPoolStray(box, opts) {
+    const profile = opts.profile ?? DEFAULT_CRABBOX_PROFILE;
+    const netMode = opts.netMode ?? 'public';
+    const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+    const graceSecs = opts.graceSecs ?? STRAY_GRACE_SECS;
+    if (box.slug === opts.keepSlug)
+        return false;
+    if (box.status !== 'running')
+        return false;
+    if ((box.profile ?? DEFAULT_CRABBOX_PROFILE) !== profile)
+        return false;
+    const boxNet = box.tailscaleIPv4 || box.tailscaleFQDN ? 'tailscale' : 'public';
+    if (boxNet !== netMode)
+        return false;
+    if (box.expiresAt === null || box.expiresAt > nowSecs)
+        return false; // unexpired ⇒ reusable
+    if (box.lastTouchedAt !== null && nowSecs - box.lastTouchedAt < graceSecs)
+        return false; // maybe active
+    return true;
+}
+/**
+ * Opportunistically stop expired, idle strays in this run's pool — rides the
+ * lease (no scheduler), best-effort (never throws, never blocks the run). Returns
+ * how many were stopped.
+ */
+function reapExpiredPoolStrays(opts, keepSlug) {
+    let boxes;
+    try {
+        boxes = crabboxList({ secretsBundle: opts.secretsBundle });
+    }
+    catch {
+        return 0;
+    }
+    let reaped = 0;
+    for (const b of boxes) {
+        if (!isExpiredPoolStray(b, { profile: opts.profile, netMode: opts.netMode, keepSlug }))
+            continue;
+        if (crabboxStop(b.slug, { secretsBundle: opts.secretsBundle }))
+            reaped++;
+    }
+    return reaped;
+}
 export async function leaseAndRun(opts) {
     const startedAt = Date.now();
     let box;
@@ -212,6 +267,13 @@ export async function leaseAndRun(opts) {
         }
     }
     opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
+    // Reap expired, idle strays in this pool now that we hold our box. An expired
+    // box can never be reused, so these are pure cost the 1h-idle `gc` window
+    // leaves running. Skip when the caller named an explicit `--box` (they're
+    // driving box lifecycle by hand). Best-effort — never blocks or aborts the run.
+    if (!opts.reuseBox) {
+        reapExpiredPoolStrays(opts, box.slug);
+    }
     // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
     // box from the host, over crabbox's own per-lease ssh (a raw ssh fails
     // publickey). rsync only here — the box has no agents-cli yet, so the matching

package/dist/lib/daemon.js

@@ -888,6 +888,45 @@ export async function runDaemon() {
     };
     const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
     const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
+    // Session-status cache warm (RUSH-2062): publish THIS host's local active
+    // sessions so menubar / Factory / watchdog / CLI share one warm snapshot
+    // instead of each re-running a full ~9s / ~170MB gather. Publish-own only
+    // (no cross-host SSH — same N² lesson as RUSH-2061). Short interval keeps
+    // live status fresh; forceRefresh still re-gathers. Additive sibling of
+    // fleetCacheInterval — does not touch the reaper tick.
+    let warmingSessionCache = false;
+    // Import once so the interval/kickoff constants stay the single source of truth
+    // (SESSION_CACHE_WARM_* in session-cache.ts). Dynamic import of the warm fn
+    // itself stays inside the tick so a cold daemon boot does not pay the load.
+    const sessionCacheWarmTiming = import('./session/session-cache.js').then((m) => ({
+        intervalMs: m.SESSION_CACHE_WARM_INTERVAL_MS,
+        kickoffMs: m.SESSION_CACHE_WARM_KICKOFF_MS,
+        publish: m.publishLocalActiveSessions,
+    }));
+    const runSessionCacheWarm = async () => {
+        if (warmingSessionCache)
+            return;
+        warmingSessionCache = true;
+        try {
+            const { publish } = await sessionCacheWarmTiming;
+            const r = await publish();
+            log('INFO', `session cache warm: ${r.sessions.length} local session(s)`);
+        }
+        catch (err) {
+            log('ERROR', `session cache warm failed: ${err.message}`);
+        }
+        finally {
+            warmingSessionCache = false;
+        }
+    };
+    // Intervals resolved from the module constants (fallback matches the defaults
+    // if the import is still pending — the first tick uses the live import).
+    let sessionCacheInterval;
+    let sessionCacheKickoff;
+    void sessionCacheWarmTiming.then(({ intervalMs, kickoffMs }) => {
+        sessionCacheInterval = setInterval(() => { void runSessionCacheWarm(); }, intervalMs);
+        sessionCacheKickoff = setTimeout(() => { void runSessionCacheWarm(); }, kickoffMs);
+    });
     // Usage refresh: keep the usage cache the `agents run` router reads
     // (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
     // This host is the sole writer for its own local accounts. The tick wakes
@@ -955,6 +994,32 @@ export async function runDaemon() {
         }
     };
     const brokerSelfHealInterval = setInterval(() => { void runBrokerSelfHeal(); }, 60_000);
+    // RUSH-2232: reap orphaned keychain helpers and `agents` processes stuck on a
+    // keychain call. Runs as a 5-min interval in the daemon (the single executor)
+    // so no UI surface can race it. The reaper shells `ps` once, plans kills in a
+    // pure function, and executes via killTree.
+    let reapingKeychain = false;
+    const runKeychainReap = async () => {
+        if (reapingKeychain)
+            return;
+        reapingKeychain = true;
+        try {
+            const { reapOrphanedKeychainProcesses } = await import('./secrets/reaper.js');
+            const result = reapOrphanedKeychainProcesses();
+            if (result.reaped > 0) {
+                log('WARN', `Reaped ${result.reaped} keychain orphan/stuck process(es)`);
+                for (const d of result.details)
+                    log('WARN', `  ${d}`);
+            }
+        }
+        catch (err) {
+            log('ERROR', `Keychain reaper failed: ${err.message}`);
+        }
+        finally {
+            reapingKeychain = false;
+        }
+    };
+    const keychainReapInterval = setInterval(() => { void runKeychainReap(); }, 5 * 60_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         // Refresh user-layer copies of opted-in project routines BEFORE the
@@ -1013,9 +1078,14 @@ export async function runDaemon() {
         clearTimeout(launchHealthKickoff);
         clearInterval(fleetCacheInterval);
         clearTimeout(fleetCacheKickoff);
+        if (sessionCacheInterval)
+            clearInterval(sessionCacheInterval);
+        if (sessionCacheKickoff)
+            clearTimeout(sessionCacheKickoff);
         clearInterval(usageRefreshInterval);
         clearTimeout(usageRefreshKickoff);
         clearInterval(brokerSelfHealInterval);
+        clearInterval(keychainReapInterval);
         hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();

package/dist/lib/exec.d.ts

@@ -86,6 +86,8 @@ export interface ModeWarningState {
  * also maps an unsupported `'plan'` request onto this same value.
  */
 export declare function defaultModeFor(agent: AgentId): Mode;
+/** Safe mode used when the user did not provide --mode or a configured default. */
+export declare function implicitModeFor(agent: AgentId): ExecMode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
@@ -97,6 +99,8 @@ export interface ExecOptions {
     /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
     interactive?: boolean;
     mode: ExecMode;
+    /** True when the caller omitted --mode; fallback agents resolve their own safe default. */
+    modeWasImplicit?: boolean;
     effort: ExecEffort;
     cwd?: string;
     /** Force headless mode even when no prompt is provided (e.g. piping via stdin). */