@crewx/cli 0.9.0-rc.128 → 0.9.0-rc.129

package/dist/builtin.d.ts

@@ -12,4 +12,4 @@ export declare const BUILTIN_COMMANDS: Set<string>;
  * Falls back to direct main() call on any tracer failure.
  */
 export declare function wrapWithTracer(builtinName: string, main: (args?: string[]) => Promise<void>, args: string[]): Promise<void>;
-export declare function handleBuiltin(builtinName: string, args: string[]): Promise<void>;
+export declare function handleBuiltin(builtinName: string, args: string[], productPackageRoot?: string): Promise<void>;

package/dist/builtin.js

@@ -106,7 +106,7 @@ async function wrapWithTracer(builtinName, main, args) {
     }
     await main(args);
 }
-async function handleBuiltin(builtinName, args) {
+async function handleBuiltin(builtinName, args, productPackageRoot) {
     const loader = BUILTIN_MAP[builtinName];
     if (!loader) {
         console.error(`Unknown built-in tool: ${builtinName}`);
@@ -114,7 +114,10 @@ async function handleBuiltin(builtinName, args) {
     }
     try {
         const mod = await loader();
-        await wrapWithTracer(builtinName, mod.main.bind(mod), args);
+        const main = builtinName === 'skill'
+            ? (skillArgs) => mod.main(skillArgs, { productPackageRoot })
+            : mod.main.bind(mod);
+        await wrapWithTracer(builtinName, main, args);
     }
     catch (err) {
         const code = err.code;

package/dist/commands/detached.d.ts

@@ -48,6 +48,12 @@ export declare function resolveReceiptMode(options: {
     detachedRunner: boolean;
     agentContext: boolean;
 }): ReceiptModeDecision;
+/**
+ * Rebuild runner argv from the parsed request. The resolved prompt is passed
+ * as one argv value after `--`, so stdin is never needed by the detached
+ * child and prompt text beginning with a dash remains positional text.
+ */
+export declare function buildDetachedRunnerArgs(filteredArgs: string[], agentRef: string, finalMessage: string): string[];
 export type AssignedTaskAdoption = {
     kind: 'adopted';
     taskId: string;
@@ -86,4 +92,4 @@ export declare function runDetachedMiddle(command: string, hop: DetachedMiddleHo
  * Persist a receipt and launch its detached runner. Unix uses one hop. Windows
  * uses a short-lived middle hop so the final runner has no live parent link.
  */
-export declare function runDetached(command: string, filteredArgs: string[], reason: ReceiptModeReason): Promise<void>;
+export declare function runDetached(command: string, filteredArgs: string[], reason: ReceiptModeReason, invocationArgs?: string[]): Promise<void>;

package/dist/commands/detached.js

@@ -12,6 +12,7 @@ exports.resolveReceiptActor = resolveReceiptActor;
 exports.reportAdmissionBlocked = reportAdmissionBlocked;
 exports.extractReceiptFlags = extractReceiptFlags;
 exports.resolveReceiptMode = resolveReceiptMode;
+exports.buildDetachedRunnerArgs = buildDetachedRunnerArgs;
 exports.adoptAssignedTask = adoptAssignedTask;
 exports.readAssignedTaskActor = readAssignedTaskActor;
 exports.readDetachedMiddleHop = readDetachedMiddleHop;
@@ -26,10 +27,12 @@ const node_1 = require("@crewx/sdk/node");
 const repository_1 = require("@crewx/sdk/repository");
 const parse_agent_message_1 = require("./parse-agent-message");
 const parse_common_flags_1 = require("./parse-common-flags");
+const resolve_recipient_1 = require("./resolve-recipient");
 const resolve_prompt_1 = require("./resolve-prompt");
 const version_1 = require("../utils/version");
 const inherited_trace_1 = require("../utils/inherited-trace");
 const cal_1 = require("./cal");
+const emit_trailer_1 = require("./emit-trailer");
 function nonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -73,6 +76,7 @@ function reportAdmissionBlocked(admission) {
 const DETACHED_RUNNER_POLL_INTERVAL_MS = 200;
 const DETACHED_RUNNER_ADOPTION_TIMEOUT_MS = 30_000;
 const DETACHED_VALUE_FLAGS = [
+    '--to',
     '--thread',
     '--provider',
     '--model',
@@ -268,6 +272,13 @@ function buildDetachedRunnerArgs(filteredArgs, agentRef, finalMessage) {
             forwarded.push(arg);
             continue;
         }
+        if (arg === '--to') {
+            // The child receives the resolved recipient as a positional @agent.
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--to='))
+            continue;
         if (!isDetachedValueFlag(arg))
             continue;
         if (isDetachedPromptFileFlag(arg)) {
@@ -426,15 +437,32 @@ async function runDetachedMiddle(command, hop) {
  * Persist a receipt and launch its detached runner. Unix uses one hop. Windows
  * uses a short-lived middle hop so the final runner has no live parent link.
  */
-async function runDetached(command, filteredArgs, reason) {
+async function runDetached(command, filteredArgs, reason, invocationArgs = filteredArgs) {
     const parsedFlags = (0, parse_common_flags_1.parseCommonFlags)(filteredArgs);
-    const { thread, metadata, promptFile, rest } = parsedFlags;
+    const { thread, metadata, promptFile, rest, to } = parsedFlags;
     const { agentRef: parsedAgentRef, message } = (0, parse_agent_message_1.parseAgentMessage)(rest);
     const finalMessage = await (0, resolve_prompt_1.resolvePrompt)(message, promptFile);
-    const agentRef = parsedAgentRef || '@crewx';
+    let agentRef;
+    try {
+        ({ agentRef } = (0, resolve_recipient_1.resolveRecipient)({
+            positionalRef: parsedAgentRef,
+            toFlag: to,
+            agentContext: Boolean(process.env['CREWX_AGENT_ID']),
+            bodyForHint: finalMessage,
+            command,
+            invocationArgs,
+        }));
+    }
+    catch (error) {
+        const messageText = errorMessage(error);
+        process.stderr.write(`Error: ${messageText}\n`);
+        (0, emit_trailer_1.emitDelegationResult)({ command, trace: (0, inherited_trace_1.readInheritedTrace)(), isError: true });
+        process.exit(2);
+        return;
+    }
     if (!finalMessage) {
-        console.error('Usage: crewx query/execute [@agent] <message> [options]');
-        console.error('  @agent is optional. Defaults to @crewx when omitted.');
+        console.error('Usage: crewx q|x --to <agent> <message> [options]');
+        console.error('  @agent is a positional shorthand for selecting a recipient.');
         console.error('  Task body can also be supplied via stdin pipe or --prompt-file.');
         process.exit(1);
         return;

package/dist/commands/execute.d.ts

@@ -3,6 +3,7 @@
  * Parses args, loads config via Crewx SDK, and executes the task.
  *
  * Flags:
+ *   --to <agent>             Explicit recipient (the positional @agent form is shorthand)
  *   --thread <name>          Conversation thread name
  *   --provider <cli/xxx>     Provider override
  *   --model <name>           Model override (e.g. claude-sonnet-5)

package/dist/commands/execute.js

@@ -4,6 +4,7 @@
  * Parses args, loads config via Crewx SDK, and executes the task.
  *
  * Flags:
+ *   --to <agent>             Explicit recipient (the positional @agent form is shorthand)
  *   --thread <name>          Conversation thread name
  *   --provider <cli/xxx>     Provider override
  *   --model <name>           Model override (e.g. claude-sonnet-5)
@@ -27,6 +28,7 @@ const sdk_1 = require("@crewx/sdk");
 const repository_1 = require("@crewx/sdk/repository");
 const parse_agent_message_1 = require("./parse-agent-message");
 const parse_common_flags_1 = require("./parse-common-flags");
+const resolve_recipient_1 = require("./resolve-recipient");
 const resolve_prompt_1 = require("./resolve-prompt");
 const crewx_cli_1 = require("../bootstrap/crewx-cli");
 const inherited_trace_1 = require("../utils/inherited-trace");
@@ -59,7 +61,7 @@ async function handleExecute(args, command = 'execute', emitState = (0, emit_tra
         agentContext: Boolean(process.env['CREWX_AGENT_ID']),
     });
     if (receiptMode.receipt) {
-        await (0, detached_1.runDetached)(command, receiptFlags.rest, receiptMode.reason);
+        await (0, detached_1.runDetached)(command, receiptFlags.rest, receiptMode.reason, args);
         return;
     }
     let parsedFlags;
@@ -70,7 +72,7 @@ async function handleExecute(args, command = 'execute', emitState = (0, emit_tra
         (0, emit_trailer_1.emitDelegationResult)({ command, isError: true, state: emitState });
         throw err;
     }
-    const { thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest } = parsedFlags;
+    const { thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest, to } = parsedFlags;
     const inheritedTrace = (0, inherited_trace_1.readInheritedTrace)();
     let parsedAgentRef;
     let message;
@@ -84,20 +86,40 @@ async function handleExecute(args, command = 'execute', emitState = (0, emit_tra
         (0, emit_trailer_1.emitDelegationResult)({ command, trace: inheritedTrace, isError: true, state: emitState });
         throw err;
     }
-    const agentRef = parsedAgentRef || '@crewx';
+    let agentRef;
+    try {
+        ({ agentRef } = (0, resolve_recipient_1.resolveRecipient)({
+            positionalRef: parsedAgentRef,
+            toFlag: to,
+            agentContext: Boolean(process.env['CREWX_AGENT_ID']),
+            bodyForHint: finalMessage,
+            command,
+            invocationArgs: args,
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${message}\n`);
+        (0, emit_trailer_1.emitDelegationResult)({ command, trace: inheritedTrace, isError: true, state: emitState });
+        process.exit(2);
+        return;
+    }
     if (!finalMessage) {
-        console.error('Usage: crewx execute [@agent] <task> [options]');
-        console.error('       crewx x [@agent] <task> [options]');
+        console.error('Usage: crewx execute --to <agent> <task> [options]');
+        console.error('       crewx x --to <agent> <task> [options]');
+        console.error('       crewx x @agent <task> [options] (@agent shorthand)');
         console.error('');
-        console.error('  @agent is optional. Defaults to @crewx when omitted.');
+        console.error('  Agent calls require --to or a positional @agent recipient.');
+        console.error('  Human terminal and cron calls default to @crewx when omitted.');
         console.error('  Task body can also be supplied via stdin pipe or --prompt-file.');
         console.error('');
         console.error('Examples:');
-        console.error('  crewx x "@agent do something"');
-        console.error('  cat task.md | crewx x "@agent label"');
-        console.error('  crewx x "@agent label" --prompt-file=task.md');
+        console.error('  crewx x --to agent do something');
+        console.error('  cat task.md | crewx x --to agent');
+        console.error('  crewx x @agent label --prompt-file=task.md');
         console.error('');
         console.error('Options:');
+        console.error('  --to <agent>              Explicit agent recipient');
         console.error('  --thread <name>           Conversation thread name');
         console.error('  --provider <cli/xxx>      Provider override');
         console.error('  --model <name>            Model override (e.g. claude-sonnet-5)');

package/dist/commands/parse-common-flags.d.ts

@@ -2,7 +2,7 @@
  * Common flag parser for query/execute commands.
  *
  * Supports both `--flag=value` and `--flag value` forms.
- * Handles: --thread, --provider, --model, --metadata, --verbose, --config/-c,
+ * Handles: --to, --thread, --provider, --model, --metadata, --verbose, --config/-c,
  *          --output-format, --effort, --prompt-file/-f, --overdrive.
  *
  * Strict mode: unknown --xxx tokens after known flags are consumed throw an
@@ -12,6 +12,8 @@
 export interface CommonFlags {
     /** Thread name for conversation continuity. */
     thread?: string;
+    /** Explicit agent recipient. */
+    to?: string;
     /** Provider override (e.g., cli/claude). */
     provider?: string;
     /** Model override (e.g., claude-sonnet-5). */

package/dist/commands/parse-common-flags.js

@@ -3,7 +3,7 @@
  * Common flag parser for query/execute commands.
  *
  * Supports both `--flag=value` and `--flag value` forms.
- * Handles: --thread, --provider, --model, --metadata, --verbose, --config/-c,
+ * Handles: --to, --thread, --provider, --model, --metadata, --verbose, --config/-c,
  *          --output-format, --effort, --prompt-file/-f, --overdrive.
  *
  * Strict mode: unknown --xxx tokens after known flags are consumed throw an
@@ -61,6 +61,7 @@ exports.UnknownOptionError = UnknownOptionError;
  * The `--` sentinel itself is NOT included in `rest`.
  */
 function parseCommonFlags(args) {
+    const { value: to, consumed: toConsumed } = parseToFlag(args);
     const thread = parseFlag(args, '--thread');
     const provider = parseFlag(args, '--provider');
     const model = parseFlag(args, '--model');
@@ -73,7 +74,7 @@ function parseCommonFlags(args) {
     const verbose = hasFlag(args, '--verbose');
     const overdrive = hasFlag(args, '--overdrive');
     // Collect consumed positions for known flags
-    const consumed = new Set();
+    const consumed = new Set(toConsumed);
     const flagPairs = [
         { names: ['--thread'] },
         { names: ['--provider'] },
@@ -149,7 +150,7 @@ function parseCommonFlags(args) {
         if (!escapeMode && token.startsWith('--')) {
             throw new UnknownOptionError(`Unknown option: ${token}. Use "--" to pass literal flag-like tokens as message.\n` +
                 `   Did you mean: crewx serve ${token}\n` +
-                `              or: crewx q -- ${token} <message>   (to include in message)`);
+                `              or: crewx q --to <agent> -- ${token} <message>`);
         }
         // Reject short -x flags that are not numeric (e.g. -f was consumed above)
         if (!escapeMode && token.startsWith('-') && token.length > 1 && !/^-?\d/.test(token)) {
@@ -157,7 +158,35 @@ function parseCommonFlags(args) {
         }
         rest.push(token);
     }
-    return { thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest };
+    return { to, thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest };
+}
+/** Parse the explicit recipient flag without treating tokens after `--` as flags. */
+function parseToFlag(args) {
+    let value;
+    const consumed = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--')
+            break;
+        if (arg.startsWith('--to=')) {
+            const candidate = arg.slice('--to='.length);
+            if (!candidate.trim())
+                throw new UnknownOptionError('--to requires an agent id');
+            value = candidate;
+            consumed.push(index);
+            continue;
+        }
+        if (arg !== '--to')
+            continue;
+        const candidate = args[index + 1];
+        if (candidate === undefined || candidate === '--' || candidate.startsWith('--') || !candidate.trim()) {
+            throw new UnknownOptionError('--to requires an agent id');
+        }
+        value = candidate;
+        consumed.push(index, index + 1);
+        index += 1;
+    }
+    return { value, consumed };
 }
 /**
  * Parse metadata JSON string from --metadata flag.

package/dist/commands/query.d.ts

@@ -3,6 +3,7 @@
  * Parses args, loads config via Crewx SDK, and executes the query.
  *
  * Flags:
+ *   --to <agent>             Explicit recipient (the positional @agent form is shorthand)
  *   --thread <name>          Conversation thread name
  *   --provider <cli/xxx>     Provider override
  *   --model <name>           Model override (e.g. claude-sonnet-5)
@@ -18,7 +19,7 @@
  *
  * Stdin support:
  *   Pipe or redirect content into crewx q to supply the prompt body via stdin.
- *   e.g. cat brief.md | crewx q "@agent label"
+ *   e.g. cat brief.md | crewx q --to agent label
  *   Stdin is ignored when running in an interactive TTY.
  */
 import { type DelegationEmitState } from './emit-trailer';

package/dist/commands/query.js

@@ -4,6 +4,7 @@
  * Parses args, loads config via Crewx SDK, and executes the query.
  *
  * Flags:
+ *   --to <agent>             Explicit recipient (the positional @agent form is shorthand)
  *   --thread <name>          Conversation thread name
  *   --provider <cli/xxx>     Provider override
  *   --model <name>           Model override (e.g. claude-sonnet-5)
@@ -19,7 +20,7 @@
  *
  * Stdin support:
  *   Pipe or redirect content into crewx q to supply the prompt body via stdin.
- *   e.g. cat brief.md | crewx q "@agent label"
+ *   e.g. cat brief.md | crewx q --to agent label
  *   Stdin is ignored when running in an interactive TTY.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -28,6 +29,7 @@ const sdk_1 = require("@crewx/sdk");
 const repository_1 = require("@crewx/sdk/repository");
 const parse_agent_message_1 = require("./parse-agent-message");
 const parse_common_flags_1 = require("./parse-common-flags");
+const resolve_recipient_1 = require("./resolve-recipient");
 const resolve_prompt_1 = require("./resolve-prompt");
 const crewx_cli_1 = require("../bootstrap/crewx-cli");
 const inherited_trace_1 = require("../utils/inherited-trace");
@@ -56,7 +58,7 @@ async function handleQuery(args, command = 'query', emitState = (0, emit_trailer
         agentContext: Boolean(process.env['CREWX_AGENT_ID']),
     });
     if (receiptMode.receipt) {
-        await (0, detached_1.runDetached)(command, receiptFlags.rest, receiptMode.reason);
+        await (0, detached_1.runDetached)(command, receiptFlags.rest, receiptMode.reason, args);
         return;
     }
     let parsedFlags;
@@ -67,7 +69,7 @@ async function handleQuery(args, command = 'query', emitState = (0, emit_trailer
         (0, emit_trailer_1.emitDelegationResult)({ command, isError: true, state: emitState });
         throw err;
     }
-    const { thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest } = parsedFlags;
+    const { thread, provider, model, metadata, verbose, config, outputFormat, effort, promptFile, overdrive, vars, out, rest, to } = parsedFlags;
     const inheritedTrace = (0, inherited_trace_1.readInheritedTrace)();
     let parsedAgentRef;
     let message;
@@ -81,20 +83,40 @@ async function handleQuery(args, command = 'query', emitState = (0, emit_trailer
         (0, emit_trailer_1.emitDelegationResult)({ command, trace: inheritedTrace, isError: true, state: emitState });
         throw err;
     }
-    const agentRef = parsedAgentRef || '@crewx';
+    let agentRef;
+    try {
+        ({ agentRef } = (0, resolve_recipient_1.resolveRecipient)({
+            positionalRef: parsedAgentRef,
+            toFlag: to,
+            agentContext: Boolean(process.env['CREWX_AGENT_ID']),
+            bodyForHint: finalMessage,
+            command,
+            invocationArgs: args,
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${message}\n`);
+        (0, emit_trailer_1.emitDelegationResult)({ command, trace: inheritedTrace, isError: true, state: emitState });
+        process.exit(2);
+        return;
+    }
     if (!finalMessage) {
-        console.error('Usage: crewx query [@agent] <message> [options]');
-        console.error('       crewx q [@agent] <message> [options]');
+        console.error('Usage: crewx query --to <agent> <message> [options]');
+        console.error('       crewx q --to <agent> <message> [options]');
+        console.error('       crewx q @agent <message> [options] (@agent shorthand)');
         console.error('');
-        console.error('  @agent is optional. Defaults to @crewx when omitted.');
+        console.error('  Agent calls require --to or a positional @agent recipient.');
+        console.error('  Human terminal and cron calls default to @crewx when omitted.');
         console.error('  Prompt can also be supplied via stdin pipe or --prompt-file.');
         console.error('');
         console.error('Examples:');
-        console.error('  crewx q "@agent hello"');
-        console.error('  cat brief.md | crewx q "@agent summarise"');
-        console.error('  crewx q "@agent label" --prompt-file=brief.md');
+        console.error('  crewx q --to agent hello');
+        console.error('  cat brief.md | crewx q --to agent');
+        console.error('  crewx q @agent label --prompt-file=brief.md');
         console.error('');
         console.error('Options:');
+        console.error('  --to <agent>              Explicit agent recipient');
         console.error('  --thread <name>           Conversation thread name');
         console.error('  --provider <cli/xxx>      Provider override');
         console.error('  --model <name>            Model override (e.g. claude-sonnet-5)');

package/dist/commands/resolve-prompt.js

@@ -14,6 +14,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStdin = readStdin;
 exports.resolvePrompt = resolvePrompt;
 const fs_1 = require("fs");
+function decodePromptFile(promptFile) {
+    const contents = (0, fs_1.readFileSync)(promptFile);
+    if (contents.length >= 3
+        && contents[0] === 0xef
+        && contents[1] === 0xbb
+        && contents[2] === 0xbf) {
+        return contents.subarray(3).toString('utf8');
+    }
+    if (contents.length >= 2 && contents[0] === 0xff && contents[1] === 0xfe) {
+        return contents.subarray(2).toString('utf16le');
+    }
+    if (contents.length >= 2 && contents[0] === 0xfe && contents[1] === 0xff) {
+        const payload = contents.subarray(2);
+        for (let index = 0; index + 1 < payload.length; index += 2) {
+            const first = payload[index];
+            payload[index] = payload[index + 1];
+            payload[index + 1] = first;
+        }
+        return payload.toString('utf16le');
+    }
+    return contents.toString('utf8');
+}
 /**
  * Read all bytes from stdin (pipe or redirect).
  * Returns empty string when stdin is a TTY (interactive terminal).
@@ -43,7 +65,7 @@ async function readStdin() {
 async function resolvePrompt(argvPrompt, promptFile, _readStdin = readStdin) {
     let external = '';
     if (promptFile) {
-        external = (0, fs_1.readFileSync)(promptFile, 'utf8').trimEnd();
+        external = decodePromptFile(promptFile).trimEnd();
     }
     else if (!argvPrompt) {
         external = (await _readStdin()).trimEnd();

package/dist/commands/resolve-recipient.d.ts

@@ -0,0 +1,14 @@
+export interface ResolveRecipientOptions {
+    positionalRef?: string;
+    toFlag?: string;
+    agentContext: boolean;
+    bodyForHint?: string;
+    command?: string;
+    invocationArgs?: string[];
+}
+export declare class RecipientResolutionError extends Error {
+    constructor(message: string);
+}
+export declare function resolveRecipient(options: ResolveRecipientOptions): {
+    agentRef: string;
+};

package/dist/commands/resolve-recipient.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecipientResolutionError = void 0;
+exports.resolveRecipient = resolveRecipient;
+class RecipientResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecipientResolutionError';
+    }
+}
+exports.RecipientResolutionError = RecipientResolutionError;
+function resolveRecipient(options) {
+    const toRef = normalizeRecipient(options.toFlag, true);
+    const positionalRef = normalizeRecipient(options.positionalRef, false);
+    if (toRef && positionalRef && toRef !== positionalRef) {
+        throw new RecipientResolutionError(`Recipient was specified twice: --to ${toRef.slice(1)} conflicts with positional ${positionalRef}.`);
+    }
+    const agentRef = toRef ?? positionalRef;
+    if (agentRef)
+        return { agentRef };
+    if (!options.agentContext)
+        return { agentRef: '@crewx' };
+    const hintedId = options.bodyForHint?.match(/^@(\S+)/u)?.[1];
+    const retryId = hintedId ?? '<agent-id>';
+    const command = options.command ?? 'query';
+    const retryArgs = (options.invocationArgs ?? []).map(formatRetryArgument).join(' ');
+    const retryCommand = `crewx ${command} --to ${retryId}${retryArgs ? ` ${retryArgs}` : ''}`;
+    throw new RecipientResolutionError('No recipient was specified. Agent calls must set one explicitly; nothing was run.\n' +
+        `Retry command: ${retryCommand}\n` +
+        'To ask the built-in assistant on purpose, use --to crewx.');
+}
+function normalizeRecipient(value, required) {
+    if (value === undefined)
+        return undefined;
+    const id = value.trim().replace(/^@/u, '');
+    if (!id) {
+        if (required)
+            throw new RecipientResolutionError('--to requires an agent id.');
+        return undefined;
+    }
+    return `@${id}`;
+}
+function formatRetryArgument(value) {
+    if (!/\s/u.test(value))
+        return value;
+    return `"${value.replaceAll('"', '\\"')}"`;
+}

package/dist/main.js

@@ -86,6 +86,7 @@ const db_1 = require("./commands/db");
 const parse_common_flags_1 = require("./commands/parse-common-flags");
 const registry_1 = require("./commands/registry");
 const version_1 = require("./utils/version");
+const product_package_root_1 = require("./utils/product-package-root");
 const emit_trailer_1 = require("./commands/emit-trailer");
 /**
  * Dev-only SSOT assertion: bin/cli-commands.js must be the exact union of
@@ -123,7 +124,10 @@ async function main(emitState) {
     }
     // Built-in tools: memory, search, doc, wbs, cron, workflow, skill
     if (builtin_1.BUILTIN_COMMANDS.has(command)) {
-        await (0, builtin_1.handleBuiltin)(command, args.slice(1));
+        const productPackageRoot = command === 'skill'
+            ? (0, product_package_root_1.resolveProductRootFromCliEntry)(process.argv[1])
+            : undefined;
+        await (0, builtin_1.handleBuiltin)(command, args.slice(1), productPackageRoot);
         return;
     }
     // Core commands
@@ -276,12 +280,14 @@ UI Modes:
   crewx electron [--overlay]     Launch Electron (desktop or overlay window)
 
 Query / Execute:
-  q|query "@agent <message>"     Query an agent (quoted single string)
-  x|execute "@agent <task>"      Execute a task with an agent (quoted single string)
+  q|query --to <agent> <message> Query an agent
+  x|execute --to <agent> <task>  Execute a task with an agent
 
-  @agent is optional — defaults to @crewx when omitted.
+  Positional @agent <message> is shorthand for selecting a recipient.
+  Agent calls require a recipient; human terminal and cron calls default to @crewx.
 
   Common flags:
+    --to <agent>                 Explicit agent recipient
     --thread <name>              Conversation thread
     --provider <cli/xxx>         Provider override
     --metadata <json>            Extra metadata (JSON object, double-quoted). Propagated to events/hooks/tracing.

package/dist/utils/product-package-root.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Finds the installed product root from the CLI entry file that is running.
+ * The real CLI path is walked to the first package named `crewx`, which must
+ * contain the compiled bundle helper. cwd and environment are deliberately ignored.
+ */
+export declare function resolveProductRootFromCliEntry(cliEntryPath: string | undefined): string | undefined;

package/dist/utils/product-package-root.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProductRootFromCliEntry = resolveProductRootFromCliEntry;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const PRODUCT_BUNDLE_HELPER = (0, node_path_1.join)('dist-server', 'common', 'product-app-bundle.js');
+/**
+ * Finds the installed product root from the CLI entry file that is running.
+ * The real CLI path is walked to the first package named `crewx`, which must
+ * contain the compiled bundle helper. cwd and environment are deliberately ignored.
+ */
+function resolveProductRootFromCliEntry(cliEntryPath) {
+    if (typeof cliEntryPath !== 'string' || cliEntryPath.trim().length === 0)
+        return undefined;
+    let realCliEntryPath;
+    try {
+        realCliEntryPath = (0, node_fs_1.realpathSync)(cliEntryPath);
+    }
+    catch {
+        return undefined;
+    }
+    let current = (0, node_path_1.dirname)(realCliEntryPath);
+    while (true) {
+        try {
+            const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(current, 'package.json'), 'utf8'));
+            if (packageJson.name === 'crewx') {
+                return (0, node_fs_1.existsSync)((0, node_path_1.join)(current, PRODUCT_BUNDLE_HELPER)) ? current : undefined;
+            }
+        }
+        catch {
+            // Continue to the next ancestor when this directory has no valid package manifest.
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/cli",
-  "version": "0.9.0-rc.128",
+  "version": "0.9.0-rc.129",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=20.19.0"
@@ -25,20 +25,20 @@
     "better-sqlite3": "*",
     "dotenv": "17.2.3",
     "isomorphic-git": "1.37.1",
-    "@crewx/sdk": "0.9.0-rc.128",
-    "@crewx/knowledge-core": "0.1.17-rc.138",
-    "@crewx/search": "0.1.10-rc.124",
-    "@crewx/memory": "0.1.23-rc.145",
-    "@crewx/wbs": "0.1.10-rc.154",
-    "@crewx/cron": "0.1.10-rc.163",
-    "@crewx/doc": "0.1.9-rc.121",
-    "@crewx/wi": "0.1.10-rc.148",
-    "@crewx/chromex": "0.1.0-rc.161",
-    "@crewx/notify": "0.1.0-rc.99",
-    "@crewx/shared": "0.0.6-rc.43",
-    "@crewx/workflow": "0.3.22-rc.174",
-    "@crewx/app": "0.1.0-rc.9",
-    "@crewx/skill": "0.1.20-rc.22"
+    "@crewx/search": "0.1.10-rc.125",
+    "@crewx/sdk": "0.9.0-rc.129",
+    "@crewx/memory": "0.1.23-rc.146",
+    "@crewx/doc": "0.1.9-rc.122",
+    "@crewx/wbs": "0.1.10-rc.155",
+    "@crewx/workflow": "0.3.22-rc.175",
+    "@crewx/cron": "0.1.10-rc.164",
+    "@crewx/skill": "0.1.20-rc.23",
+    "@crewx/notify": "0.1.0-rc.100",
+    "@crewx/app": "0.1.0-rc.10",
+    "@crewx/knowledge-core": "0.1.17-rc.139",
+    "@crewx/wi": "0.1.10-rc.149",
+    "@crewx/shared": "0.0.6-rc.44",
+    "@crewx/chromex": "0.1.0-rc.162"
   },
   "devDependencies": {
     "@types/better-sqlite3": "*",