@genspark/cli 1.5.4 → 1.6.2

package/dist/index.js

@@ -31,6 +31,7 @@ import { classifyFileArg, awaitLocalFileReady, decideAfterWait, localFileNotRead
 import { setDebugEnabled, setOutputFormat, debug, info, warn, error as logError, output, } from './logger.js';
 import { loadConfigFile, getConfigPath, loadToolsCache, normalizeBaseUrl, saveToolsCache, setConfigPathOverride, updateConfigFile, } from './config.js';
 import { checkForUpdates } from './updater.js';
+import { addRegisteredCommands, collectToolCommandTokens, staleCacheMissingToken, } from './staleCache.js';
 import { shimLegacyTaskInvocation } from './task-shim.js';
 import { getSandboxRuntime } from './runtime.js';
 import { registerDesignCommand } from './commands/design.js';
@@ -39,6 +40,7 @@ import { parseLastSeenIndex, eventStdoutLine } from './commands/chat-events.js';
 import { mediaItemsKeyFor, mediaSummaryLines } from './mediaSummary.js';
 import { registerMeshCommand, getMeshInvocation, runMesh, } from './commands/mesh.js';
 import { executeCloneUrl, normalizeCloneUrlForGit, } from './commands/sb-git-clone.js';
+import { actionScopedDescription, serviceActionViews, } from './serviceActions.js';
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../package.json');
 const DEFAULT_BASE_URL = 'https://www.genspark.ai';
@@ -576,6 +578,50 @@ function parseBooleanFlagValue(value) {
         return false;
     throw new InvalidArgumentError(`expected true/false. If '${value}' was meant as an argument, place it before the flag or pass an explicit value (--flag true ${value}).`);
 }
+/**
+ * Register one schema parameter as a Commander option.
+ *
+ * Shared by the union-flag command and the per-action subcommands so both
+ * views parse a given flag identically. Booleans accept an optional literal
+ * value (`--flag` alone is true, `--flag false` is false — a bare presence
+ * flag reads the literal as a stray positional and stays true, the silent
+ * inversion that once sent a phone number into a place-id lookup). Single
+ * -char aliases are short flags (-n); multi-char aliases must be long flags
+ * (--page) — commander treats `-page` as a literal short flag. A flag with
+ * an injected default always uses `option` (never `requiredOption`):
+ * Commander treats a defaulted flag as satisfied.
+ */
+function addSchemaOption(cmd, name, param, o) {
+    const paramType = Array.isArray(param.type) ? param.type[0] : param.type;
+    const shortPrefix = o.shortAlias
+        ? `${o.shortAlias.length > 1 ? '--' : '-'}${o.shortAlias}, `
+        : '';
+    const desc = o.description || param.description || name;
+    if (paramType === 'array') {
+        const flag = `${shortPrefix}--${name} <values...>`;
+        if (o.isRequired) {
+            cmd.requiredOption(flag, desc);
+        }
+        else {
+            cmd.option(flag, desc);
+        }
+    }
+    else if (paramType === 'boolean') {
+        cmd.option(`${shortPrefix}--${name} [value]`, desc, parseBooleanFlagValue);
+    }
+    else {
+        const flag = `${shortPrefix}--${name} <value>`;
+        if (o.injectedDefault !== undefined) {
+            cmd.option(flag, desc, o.injectedDefault);
+        }
+        else if (o.isRequired) {
+            cmd.requiredOption(flag, desc);
+        }
+        else {
+            cmd.option(flag, desc);
+        }
+    }
+}
 /**
  * Register a dynamic tool command from a server-provided schema.
  *
@@ -656,6 +702,17 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
     // everything optional in that case; the action handler re-validates the
     // required set AFTER the file merge (#46011).
     const argsFileInvoked = process.argv.some(a => a === '--args-file' || a.startsWith('--args-file='));
+    // Per-action subcommand mode (issue #51377): when the server sends the
+    // per-action parameter map, each action registers below as a real
+    // Commander subcommand with flags scoped to it. The parent must then NOT
+    // own the union flags: in Commander's default (non-positional) mode a
+    // parent consumes every option it knows from the whole line BEFORE
+    // dispatching, so union flags on the parent would swallow `--chat_id`
+    // away from `gsk teams read_chat --chat_id ...`. With no union flags the
+    // tokens flow down as unknowns to the dispatched subcommand, which
+    // accepts its own and rejects wrong-action flags at parse time. Hidden
+    // legacy forms keep the union view.
+    const actionViews = cmdOpts?.deprecated ? null : serviceActionViews(tool);
     // If primary_arg is set, make it a positional argument
     if (tool.cli.primary_arg && props[tool.cli.primary_arg]) {
         const param = props[tool.cli.primary_arg];
@@ -674,9 +731,14 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             : `[${argName}]`;
         cmd.argument(bracket, param.description || argName);
     }
-    // Add remaining params as --options
+    // Add remaining params as --options (union view). Skipped in per-action
+    // subcommand mode — see the actionViews comment above; the parent then
+    // keeps only the [action] positional (bare invocation → action listing;
+    // unknown action names still reach the server) and --args-file.
     const aliases = tool.cli.parameter_aliases || {};
     for (const [name, param] of Object.entries(props)) {
+        if (actionViews)
+            break;
         if (name === tool.cli.primary_arg)
             continue;
         // For create_task, make params optional so --acp mode works without them.
@@ -690,51 +752,16 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
             argsFileInvoked
             ? false
             : required.includes(name);
-        const paramType = Array.isArray(param.type) ? param.type[0] : param.type;
-        // Single-char aliases are short flags (-n); multi-char aliases must be
-        // long flags (--page) — commander treats `-page` as a literal short flag,
-        // so the documented `--page` form would fail with "unknown option".
-        const shortAlias = aliases[name];
-        const shortPrefix = shortAlias
-            ? `${shortAlias.length > 1 ? '--' : '-'}${shortAlias}, `
-            : '';
         // Auto-inject default for vd_project_id on tools in the `vd` group so
-        // users don't retype it on every call.  When a default is present we
-        // always use `option` (not `requiredOption`) — Commander treats a flag
-        // with a default value as satisfied and skips the required-missing
-        // check, which is the behaviour we want here.
+        // users don't retype it on every call.
         const injectedDefault = tool.cli.group === 'vd' && name === 'vd_project_id'
             ? vdProjectIdDefault
             : undefined;
-        if (paramType === 'array') {
-            const flag = `${shortPrefix}--${name} <values...>`;
-            if (isRequired) {
-                cmd.requiredOption(flag, param.description || name);
-            }
-            else {
-                cmd.option(flag, param.description || name);
-            }
-        }
-        else if (paramType === 'boolean') {
-            // Accept an optional literal value: `--flag` alone means true, but
-            // `--flag false` must mean false. With a bare presence flag Commander
-            // treats the literal as a stray positional and the flag still reads
-            // true — that silent inversion once sent a phone number into a Maps
-            // place-id lookup (`--is_place_id false`).
-            cmd.option(`${shortPrefix}--${name} [value]`, param.description || name, parseBooleanFlagValue);
-        }
-        else {
-            const flag = `${shortPrefix}--${name} <value>`;
-            if (injectedDefault !== undefined) {
-                cmd.option(flag, param.description || name, injectedDefault);
-            }
-            else if (isRequired) {
-                cmd.requiredOption(flag, param.description || name);
-            }
-            else {
-                cmd.option(flag, param.description || name);
-            }
-        }
+        addSchemaOption(cmd, name, param, {
+            isRequired,
+            shortAlias: aliases[name],
+            injectedDefault,
+        });
     }
     // For tools that expose an `attachments` array (email send/draft/reply/
     // forward across gmail + outlook), also surface human-friendly aliases
@@ -746,7 +773,7 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         (Array.isArray(props.attachments.type)
             ? props.attachments.type.includes('array')
             : props.attachments.type === 'array');
-    if (hasAttachmentsParam) {
+    if (hasAttachmentsParam && !actionViews) {
         cmd.option('--attach <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
         cmd.option('--attachment <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
     }
@@ -758,9 +785,11 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
         'quotes, newlines) instead of double-quoted flags. Server ' +
         'parameters only — CLI-only options (e.g. --local_file) must ' +
         'still be passed as flags.');
-    // Add -o/--output-file option for tools that produce downloadable files
+    // Add -o/--output-file option for tools that produce downloadable files.
+    // In per-action subcommand mode the subcommands own the flag — on the
+    // parent it would be consumed pre-dispatch and lost (see actionViews).
     const outputFileKeys = tool.cli.output_file_keys || [];
-    if (outputFileKeys.length > 0) {
+    if (outputFileKeys.length > 0 && !actionViews) {
         cmd.option('-o, --output-file <path>', 'Download the generated file to a local path');
     }
     // task ask (task_continue) shares the async-first submit → --follow
@@ -826,657 +855,708 @@ function registerToolCommand(parentProgram, tool, clientFactory, vdProjectIdDefa
     if (tool.name === 'skills_save') {
         cmd.argument('[path]', 'Local skill directory to save (default: current directory)');
     }
-    // Generic action handler
-    cmd.action(async (primaryArgValue, opts) => {
-        // Commander passes opts as second arg when there's an argument,
-        // or as first arg when there's no argument
-        if (typeof primaryArgValue === 'object' && primaryArgValue !== null) {
-            opts = primaryArgValue;
-            primaryArgValue = undefined;
-        }
-        // Service tool invoked with no action → list the available actions
-        // instead of failing on the (intentionally optional) action positional.
-        const actionEnum = tool.cli.primary_arg
-            ? props[tool.cli.primary_arg]?.enum
-            : undefined;
-        if (tool.cli.primary_arg === 'action' &&
-            Array.isArray(actionEnum) &&
-            primaryArgValue === undefined &&
-            // The action may arrive via --args-file (read later in the
-            // handler) — don't short-circuit to the action listing then.
-            !opts.argsFile) {
-            logError(tool.description);
-            logError(`Available actions: ${actionEnum.join(', ')}`);
-            logError(`Usage: gsk ${cmd.name()} <action> [options]  ` +
-                `(run \`gsk ${cmd.name()} --help\` for per-action options)`);
-            process.exit(1);
-        }
-        try {
-            // get-project: local file lookup for ACP session project info.
-            // Handled here (not as a Commander subcommand) to avoid
-            // Commander's subcommand-vs-positional-arg conflict.
-            if (tool.name === 'create_task' && primaryArgValue === 'get-project') {
-                const { loadPersistedSession, sanitizeId } = await import('./acp-serve.js');
-                const rawId = opts.sessionId || '';
-                const sessionId = sanitizeId(rawId);
-                if (!sessionId) {
-                    logError('Invalid or missing --session-id');
-                    process.exit(1);
-                }
-                const data = loadPersistedSession(sessionId);
-                if (!data) {
-                    output({ status: 'pending' });
-                    process.exitCode = 1;
-                    return;
-                }
-                const baseUrl = getGlobalOptions().baseUrl.replace(/\/$/, '');
-                output({
-                    session_id: data.sessionId,
-                    project_id: data.projectId,
-                    project_url: `${baseUrl}/agents?id=${data.projectId}`,
-                    task_type: data.taskType,
-                });
-                return;
+    // Generic invocation body — shared by the union command's action handler
+    // and (for service tools) the per-action subcommands, which call it with
+    // the action name pre-bound. `invokedCmd` is whichever Commander command
+    // actually parsed this invocation (operand access below reads its .args).
+    const runToolInvocation = async (primaryArgValue, opts, invokedCmd = cmd) => {
+        {
+            // Commander passes opts as second arg when there's an argument,
+            // or as first arg when there's no argument
+            if (typeof primaryArgValue === 'object' && primaryArgValue !== null) {
+                opts = primaryArgValue;
+                primaryArgValue = undefined;
             }
-            // ACP mode: enter stdio bridge instead of one-shot execution
-            if (tool.name === 'create_task' && opts.acp) {
-                const taskType = primaryArgValue;
-                if (!taskType) {
-                    logError('Task type is required for ACP mode. Usage: gsk task <type> --acp');
-                    process.exit(1);
-                }
-                delete opts.acp;
-                const { startAcpBridge } = await import('./acp-serve.js');
-                await startAcpBridge(taskType, clientFactory().getOptions());
-                return;
+            // Service tool invoked with no action → list the available actions
+            // instead of failing on the (intentionally optional) action positional.
+            const actionEnum = tool.cli.primary_arg
+                ? props[tool.cli.primary_arg]?.enum
+                : undefined;
+            if (tool.cli.primary_arg === 'action' &&
+                Array.isArray(actionEnum) &&
+                primaryArgValue === undefined &&
+                // The action may arrive via --args-file (read later in the
+                // handler) — don't short-circuit to the action listing then.
+                !opts.argsFile) {
+                logError(tool.description);
+                logError(`Available actions: ${actionEnum.join(', ')}`);
+                logError(`Usage: gsk ${cmd.name()} <action> [options]  ` +
+                    `(run \`gsk ${cmd.name()} --help\` for per-action options)`);
+                process.exit(1);
             }
-            // For create_task (non-ACP): validate required params manually.
-            // Skipped when --args-file is present — required params may live in
-            // the file, and the post-merge revalidation below enforces them.
-            if (tool.name === 'create_task' && !opts.argsFile) {
-                for (const reqParam of required) {
-                    if (reqParam === tool.cli.primary_arg)
-                        continue;
-                    if (opts[reqParam] === undefined || opts[reqParam] === null) {
-                        logError(`Missing required option: --${reqParam}`);
+            try {
+                // get-project: local file lookup for ACP session project info.
+                // Handled here (not as a Commander subcommand) to avoid
+                // Commander's subcommand-vs-positional-arg conflict.
+                if (tool.name === 'create_task' && primaryArgValue === 'get-project') {
+                    const { loadPersistedSession, sanitizeId } = await import('./acp-serve.js');
+                    const rawId = opts.sessionId || '';
+                    const sessionId = sanitizeId(rawId);
+                    if (!sessionId) {
+                        logError('Invalid or missing --session-id');
+                        process.exit(1);
+                    }
+                    const data = loadPersistedSession(sessionId);
+                    if (!data) {
+                        output({ status: 'pending' });
+                        process.exitCode = 1;
+                        return;
+                    }
+                    const baseUrl = getGlobalOptions().baseUrl.replace(/\/$/, '');
+                    output({
+                        session_id: data.sessionId,
+                        project_id: data.projectId,
+                        project_url: `${baseUrl}/agents?id=${data.projectId}`,
+                        task_type: data.taskType,
+                    });
+                    return;
+                }
+                // ACP mode: enter stdio bridge instead of one-shot execution
+                if (tool.name === 'create_task' && opts.acp) {
+                    const taskType = primaryArgValue;
+                    if (!taskType) {
+                        logError('Task type is required for ACP mode. Usage: gsk task <type> --acp');
                         process.exit(1);
                     }
+                    delete opts.acp;
+                    const { startAcpBridge } = await import('./acp-serve.js');
+                    await startAcpBridge(taskType, clientFactory().getOptions());
+                    return;
                 }
-            }
-            const client = clientFactory();
-            // Deprecated legacy form: warn on stderr (agents only relearn from
-            // invocation-time feedback, not from hidden help text) and tag the
-            // request so the server's deprecation telemetry can count it.
-            if (cmdOpts?.deprecated) {
-                // Group-qualify the legacy label so `gsk phone-call status` and
-                // the flat `gsk call_status` count as distinct legacy forms.
-                const legacyName = tool.cli.group
-                    ? `${tool.cli.group} ${cmdName}`
-                    : cmdName;
-                console.error(`[DEPRECATED] \`gsk ${legacyName}\` still works but is deprecated — ` +
-                    `use \`${cmdOpts.deprecated.replacement}\` instead.`);
-                client.setInvokedAs(`${legacyName} (legacy)`);
-            }
-            else {
-                client.setInvokedAs(tool.cli.path && tool.cli.path.length >= 2
-                    ? tool.cli.path.join(' ')
-                    : tool.cli.group
-                        ? `${tool.cli.group} ${cmdName}`
-                        : cmdName);
-            }
-            // Extract and remove client-side-only options before sending to API
-            const outputFilePath = opts.outputFile;
-            delete opts.outputFile;
-            delete opts.acp; // ACP flag is client-side only
-            // -o exports an artifact of the FINISHED project — an async submit
-            // stub has nothing to export yet, so an export request implies the
-            // live follow.
-            const attachTask = !!opts.follow || !!outputFilePath;
-            delete opts.follow; // client-side only
-            delete opts.sessionId; // get-project flag is client-side only
-            const argsFilePath = opts.argsFile;
-            delete opts.argsFile; // client-side only; merged below
-            // Required checks were relaxed because --args-file appeared in argv;
-            // an explicitly EMPTY value (`--args-file=` / `--args-file ""`,
-            // parsed as '') would skip the merge AND the revalidation below — a
-            // validation bypass, not a degenerate no-op. Refuse it. undefined is
-            // deliberately allowed: argv detection can false-positive on a
-            // literal "--args-file" VALUE of another option, and the server-side
-            // required validation still covers that arm.
-            if (argsFilePath !== undefined && !argsFilePath) {
-                logError('--args-file requires a non-empty path (or "-" for stdin)');
-                process.exit(1);
-            }
-            const args = { ...opts };
-            // Set primary arg
-            if (tool.cli.primary_arg && primaryArgValue !== undefined) {
-                args[tool.cli.primary_arg] = primaryArgValue;
-            }
-            // Merge --attach / --attachment aliases into args.attachments
-            // before sending to the API so the server sees a single field.
-            // Order: --attachments first (canonical), then --attach, then
-            // --attachment, mirroring how Commander stores variadics.
-            if (hasAttachmentsParam) {
-                const merged = [];
-                for (const key of ['attachments', 'attach', 'attachment']) {
-                    const val = opts[key];
-                    if (Array.isArray(val)) {
-                        for (const item of val) {
-                            if (typeof item === 'string')
-                                merged.push(item);
+                // For create_task (non-ACP): validate required params manually.
+                // Skipped when --args-file is present — required params may live in
+                // the file, and the post-merge revalidation below enforces them.
+                if (tool.name === 'create_task' && !opts.argsFile) {
+                    for (const reqParam of required) {
+                        if (reqParam === tool.cli.primary_arg)
+                            continue;
+                        if (opts[reqParam] === undefined || opts[reqParam] === null) {
+                            logError(`Missing required option: --${reqParam}`);
+                            process.exit(1);
                         }
                     }
                 }
-                if (merged.length > 0) {
-                    args.attachments = merged;
+                const client = clientFactory();
+                // Deprecated legacy form: warn on stderr (agents only relearn from
+                // invocation-time feedback, not from hidden help text) and tag the
+                // request so the server's deprecation telemetry can count it.
+                if (cmdOpts?.deprecated) {
+                    // Group-qualify the legacy label so `gsk phone-call status` and
+                    // the flat `gsk call_status` count as distinct legacy forms.
+                    const legacyName = tool.cli.group
+                        ? `${tool.cli.group} ${cmdName}`
+                        : cmdName;
+                    console.error(`[DEPRECATED] \`gsk ${legacyName}\` still works but is deprecated — ` +
+                        `use \`${cmdOpts.deprecated.replacement}\` instead.`);
+                    client.setInvokedAs(`${legacyName} (legacy)`);
                 }
                 else {
-                    delete args.attachments;
-                }
-                // The aliases are CLI-only; the server doesn't know about them.
-                delete args.attach;
-                delete args.attachment;
-            }
-            // Merge --args-file after every flag-derived write (positional,
-            // attachment aliases) so file keys genuinely win: the file is the
-            // deliberate rich payload, flags are the convenience layer (#46011).
-            // It sits before the numeric coercion below so file-provided
-            // numeric strings get the same schema-driven coercion flags do.
-            if (argsFilePath) {
-                let fileArgs;
-                try {
-                    const { readArgsFile } = await import('./argsFile.js');
-                    fileArgs = readArgsFile(argsFilePath);
+                    client.setInvokedAs(tool.cli.path && tool.cli.path.length >= 2
+                        ? tool.cli.path.join(' ')
+                        : tool.cli.group
+                            ? `${tool.cli.group} ${cmdName}`
+                            : cmdName);
                 }
-                catch (err) {
-                    logError(err.message);
+                // Extract and remove client-side-only options before sending to API
+                const outputFilePath = opts.outputFile;
+                delete opts.outputFile;
+                delete opts.acp; // ACP flag is client-side only
+                // -o exports an artifact of the FINISHED project — an async submit
+                // stub has nothing to export yet, so an export request implies the
+                // live follow.
+                const attachTask = !!opts.follow || !!outputFilePath;
+                delete opts.follow; // client-side only
+                delete opts.sessionId; // get-project flag is client-side only
+                // In per-action subcommand mode the PARENT registers --args-file
+                // (for the action-in-file invocation) and therefore consumes the
+                // flag pre-dispatch even when a subcommand runs — fall back to the
+                // parent's parsed value so `gsk teams read_chat --args-file f.json`
+                // is honored, never silently dropped.
+                const argsFilePath = (opts.argsFile ??
+                    (invokedCmd !== cmd ? cmd.opts().argsFile : undefined));
+                delete opts.argsFile; // client-side only; merged below
+                // Required checks were relaxed because --args-file appeared in argv;
+                // an explicitly EMPTY value (`--args-file=` / `--args-file ""`,
+                // parsed as '') would skip the merge AND the revalidation below — a
+                // validation bypass, not a degenerate no-op. Refuse it. undefined is
+                // deliberately allowed: argv detection can false-positive on a
+                // literal "--args-file" VALUE of another option, and the server-side
+                // required validation still covers that arm.
+                if (argsFilePath !== undefined && !argsFilePath) {
+                    logError('--args-file requires a non-empty path (or "-" for stdin)');
                     process.exit(1);
                 }
-                // The file carries SERVER parameters only. CLI-only options
-                // (--local_file, --file, --out, ...) are processed from flags by
-                // client-side blocks below that never see the file — honoring
-                // them here would silently do nothing, so warn and drop instead.
-                for (const key of Object.keys(fileArgs)) {
-                    if (!(key in props)) {
-                        warn(`--args-file: "${key}" is not a server parameter of ` +
-                            `${tool.name} and was ignored — CLI-only options must be ` +
-                            'passed as flags.');
-                        delete fileArgs[key];
+                const args = { ...opts };
+                // Set primary arg
+                if (tool.cli.primary_arg && primaryArgValue !== undefined) {
+                    args[tool.cli.primary_arg] = primaryArgValue;
+                }
+                // Merge --attach / --attachment aliases into args.attachments
+                // before sending to the API so the server sees a single field.
+                // Order: --attachments first (canonical), then --attach, then
+                // --attachment, mirroring how Commander stores variadics.
+                if (hasAttachmentsParam) {
+                    const merged = [];
+                    for (const key of ['attachments', 'attach', 'attachment']) {
+                        const val = opts[key];
+                        if (Array.isArray(val)) {
+                            for (const item of val) {
+                                if (typeof item === 'string')
+                                    merged.push(item);
+                            }
+                        }
+                    }
+                    if (merged.length > 0) {
+                        args.attachments = merged;
+                    }
+                    else {
+                        delete args.attachments;
                     }
+                    // The aliases are CLI-only; the server doesn't know about them.
+                    delete args.attach;
+                    delete args.attachment;
                 }
-                Object.assign(args, fileArgs);
-                // Required params were registered optional because the file may
-                // carry them (Commander validates before the file is readable) —
-                // re-validate the merged set now. CLI-populated params are
-                // exempt: skills_save's `files` is schema-required but filled by
-                // the directory collector further down, which deliberately owns
-                // the value (file-wins does not apply to collector-owned params).
-                for (const reqParam of required) {
-                    if (tool.name === 'skills_save' && reqParam === 'files')
-                        continue;
-                    if (args[reqParam] === undefined || args[reqParam] === null) {
-                        // The primary arg is a positional — there is no --<name>
-                        // flag for it, so the recovery hint must not invent one.
-                        const hint = reqParam === tool.cli.primary_arg
-                            ? `pass it as the positional argument or include it in --args-file`
-                            : `pass --${reqParam} or include it in --args-file`;
-                        logError(`Missing required parameter: ${reqParam} (${hint})`);
+                // Merge --args-file after every flag-derived write (positional,
+                // attachment aliases) so file keys genuinely win: the file is the
+                // deliberate rich payload, flags are the convenience layer (#46011).
+                // It sits before the numeric coercion below so file-provided
+                // numeric strings get the same schema-driven coercion flags do.
+                if (argsFilePath) {
+                    let fileArgs;
+                    try {
+                        const { readArgsFile } = await import('./argsFile.js');
+                        fileArgs = readArgsFile(argsFilePath);
+                    }
+                    catch (err) {
+                        logError(err.message);
                         process.exit(1);
                     }
-                }
-            }
-            // Coerce numeric strings to numbers based on schema
-            for (const [name, param] of Object.entries(props)) {
-                if (args[name] !== undefined) {
-                    const paramType = Array.isArray(param.type)
-                        ? param.type[0]
-                        : param.type;
-                    if (paramType === 'integer' || paramType === 'number') {
-                        const num = Number(args[name]);
-                        if (!isNaN(num)) {
-                            args[name] = paramType === 'integer' ? Math.floor(num) : num;
+                    // The file carries SERVER parameters only. CLI-only options
+                    // (--local_file, --file, --out, ...) are processed from flags by
+                    // client-side blocks below that never see the file — honoring
+                    // them here would silently do nothing, so warn and drop instead.
+                    for (const key of Object.keys(fileArgs)) {
+                        if (!(key in props)) {
+                            warn(`--args-file: "${key}" is not a server parameter of ` +
+                                `${tool.name} and was ignored — CLI-only options must be ` +
+                                'passed as flags.');
+                            delete fileArgs[key];
+                        }
+                    }
+                    Object.assign(args, fileArgs);
+                    // Required params were registered optional because the file may
+                    // carry them (Commander validates before the file is readable) —
+                    // re-validate the merged set now. CLI-populated params are
+                    // exempt: skills_save's `files` is schema-required but filled by
+                    // the directory collector further down, which deliberately owns
+                    // the value (file-wins does not apply to collector-owned params).
+                    for (const reqParam of required) {
+                        if (tool.name === 'skills_save' && reqParam === 'files')
+                            continue;
+                        if (args[reqParam] === undefined || args[reqParam] === null) {
+                            // The primary arg is a positional — there is no --<name>
+                            // flag for it, so the recovery hint must not invent one.
+                            const hint = reqParam === tool.cli.primary_arg
+                                ? `pass it as the positional argument or include it in --args-file`
+                                : `pass --${reqParam} or include it in --args-file`;
+                            logError(`Missing required parameter: ${reqParam} (${hint})`);
+                            process.exit(1);
                         }
                     }
                 }
-            }
-            // aidrive: strip client-side-only options before sending to API.
-            // --local_file and --override are only meaningful to the CLI and must
-            // never be forwarded to the server (other aidrive actions like ls,
-            // mkdir, move don't know about them).
-            if (tool.name === 'aidrive') {
-                delete args.local_file;
-                delete args.override;
-            }
-            // sb-git --execute is client-side only; never forward.
-            let sbGitExecuteDest;
-            let sbGitExecuteRequested = false;
-            if (tool.name === 'sb-git') {
-                const execVal = args.execute;
-                if (execVal !== undefined) {
-                    sbGitExecuteRequested = true;
-                    sbGitExecuteDest =
-                        typeof execVal === 'string' && execVal.length > 0
-                            ? execVal
-                            : undefined;
-                }
-                delete args.execute;
-            }
-            // skills pull --out is client-side only; never forward. `pull` always
-            // materialises to disk (default ./<slug>); --out just overrides where.
-            let skillsPullOut;
-            if (tool.name === 'skills_pull') {
-                const outVal = args.out;
-                skillsPullOut =
-                    typeof outVal === 'string' && outVal.length > 0 ? outVal : undefined;
-                delete args.out;
-            }
-            // skills sync: --check/--mount-dir/--store-dir are CLI-only. The
-            // digest `state` sent to the server is always computed here (from
-            // the on-disk state file the materializer loop owns), never
-            // accepted as user input.
-            let skillsSyncCheck = false;
-            let skillsSyncStoreDir = '';
-            let skillsSyncMountDir = '';
-            if (tool.name === 'skills_sync') {
-                const { loadState, defaultStoreDir, defaultMountDir } = await import('./commands/skills-sync.js');
-                skillsSyncCheck = !!args.check;
-                skillsSyncStoreDir = args.storeDir
-                    ? expandHome(args.storeDir)
-                    : defaultStoreDir();
-                skillsSyncMountDir = args.mountDir
-                    ? expandHome(args.mountDir)
-                    : defaultMountDir();
-                delete args.check;
-                delete args.storeDir;
-                delete args.mountDir;
-                args.state = JSON.stringify(loadState(skillsSyncStoreDir));
-            }
-            // skills save: read the local directory (default cwd) and ship its
-            // files inline — the inverse of `skills pull`. Client-side because
-            // only the local machine can walk a directory tree.
-            if (tool.name === 'skills_save') {
-                const { collectSkillDir } = await import('./commands/skills-save.js');
-                const dir = pathModule.resolve(primaryArgValue || '.');
-                let collected;
-                try {
-                    collected = collectSkillDir(dir);
+                // Coerce numeric strings to numbers based on schema
+                for (const [name, param] of Object.entries(props)) {
+                    if (args[name] !== undefined) {
+                        const paramType = Array.isArray(param.type)
+                            ? param.type[0]
+                            : param.type;
+                        if (paramType === 'integer' || paramType === 'number') {
+                            const num = Number(args[name]);
+                            if (!isNaN(num)) {
+                                args[name] = paramType === 'integer' ? Math.floor(num) : num;
+                            }
+                        }
+                    }
                 }
-                catch (e) {
-                    logError(`skills save: ${e.message}`);
-                    process.exit(1);
+                // aidrive: strip client-side-only options before sending to API.
+                // --local_file and --override are only meaningful to the CLI and must
+                // never be forwarded to the server (other aidrive actions like ls,
+                // mkdir, move don't know about them).
+                if (tool.name === 'aidrive') {
+                    delete args.local_file;
+                    delete args.override;
                 }
-                if (collected.sidecarOwner) {
-                    info(`Warning: ${dir} carries provenance for ${collected.sidecarOwner} — ` +
-                        `saving will fork this skill into your own catalog.`);
+                // sb-git --execute is client-side only; never forward.
+                let sbGitExecuteDest;
+                let sbGitExecuteRequested = false;
+                if (tool.name === 'sb-git') {
+                    const execVal = args.execute;
+                    if (execVal !== undefined) {
+                        sbGitExecuteRequested = true;
+                        sbGitExecuteDest =
+                            typeof execVal === 'string' && execVal.length > 0
+                                ? execVal
+                                : undefined;
+                    }
+                    delete args.execute;
                 }
-                // Collector-owned: `files` must be {path, content} read from the
-                // local directory, so this assignment intentionally overrides any
-                // --args-file value (the file-wins rule covers flag-shaped params
-                // only, not CLI-populated ones).
-                args.files = collected.files;
-            }
-            // aidrive upload ergonomics: `gsk aidrive upload <path>` is the natural
-            // invocation and the dominant fumble — the bare path is an excess
-            // operand that Commander tolerates but never maps to an option, so the
-            // request otherwise reaches the API with no content and fails with a
-            // misleading "Missing file_content". When no explicit content source was
-            // given, adopt a path-like operand as --local_file (cmd.args[0] is the
-            // 'upload' action; later operands are candidate paths, directories
-            // skipped) so the streaming upload below handles it; if there is still
-            // no usable source, fail with an actionable message that names
-            // --local_file rather than the opaque backend error.
-            if (tool.name === 'aidrive' &&
-                // args.action, not the positional: the action may arrive via
-                // --args-file (sb-git's clone-url gate uses the same pattern).
-                args.action === 'upload' &&
-                !opts.local_file &&
-                // args, not opts: file_content is a server param and may have
-                // arrived via --args-file (merged into args above).
-                !args.file_content) {
-                // Skip the first operand only when it really is the action: with
-                // the action arriving via --args-file, Commander binds a bare
-                // path to the [action] positional slot, so cmd.args[0] is itself
-                // a path candidate.
-                const operandCandidates = primaryArgValue !== undefined && primaryArgValue === args.action
-                    ? cmd.args.slice(1)
-                    : cmd.args;
-                const pathOperand = pickExistingUploadOperand(operandCandidates);
-                if (pathOperand) {
-                    opts.local_file = pathOperand;
+                // skills pull --out is client-side only; never forward. `pull` always
+                // materialises to disk (default ./<slug>); --out just overrides where.
+                let skillsPullOut;
+                if (tool.name === 'skills_pull') {
+                    const outVal = args.out;
+                    skillsPullOut =
+                        typeof outVal === 'string' && outVal.length > 0 ? outVal : undefined;
+                    delete args.out;
                 }
-                else {
-                    logError('upload needs a file source: use `--local_file <path>` for a ' +
-                        'local file (any size, binaries OK) or `--file_content <text>` ' +
-                        'for inline text. Example: gsk aidrive upload --local_file ' +
-                        './report.pdf --upload_path /report.pdf');
-                    process.exit(1);
+                // skills sync: --check/--mount-dir/--store-dir are CLI-only. The
+                // digest `state` sent to the server is always computed here (from
+                // the on-disk state file the materializer loop owns), never
+                // accepted as user input.
+                let skillsSyncCheck = false;
+                let skillsSyncStoreDir = '';
+                let skillsSyncMountDir = '';
+                if (tool.name === 'skills_sync') {
+                    const { loadState, defaultStoreDir, defaultMountDir } = await import('./commands/skills-sync.js');
+                    skillsSyncCheck = !!args.check;
+                    skillsSyncStoreDir = args.storeDir
+                        ? expandHome(args.storeDir)
+                        : defaultStoreDir();
+                    skillsSyncMountDir = args.mountDir
+                        ? expandHome(args.mountDir)
+                        : defaultMountDir();
+                    delete args.check;
+                    delete args.storeDir;
+                    delete args.mountDir;
+                    args.state = JSON.stringify(loadState(skillsSyncStoreDir));
                 }
-            }
-            // aidrive: handle --local_file for the upload action.
-            // Stream the file directly to AI Drive via the dedicated tool_cli
-            // endpoint (POST /api/tool_cli/aidrive/upload) — no blob middleman.
-            if (tool.name === 'aidrive' &&
-                args.action === 'upload' &&
-                opts.local_file) {
-                const localFilePath = opts.local_file;
-                const override = !!opts.override;
-                const workspace = args.workspace || 'personal';
-                if (!fs.existsSync(localFilePath)) {
-                    logError(`File not found: ${localFilePath}`);
-                    process.exit(1);
-                }
-                // args.upload_path is safe here: args = { ...opts } at line above, and
-                // only local_file/override were deleted from args — upload_path is intact.
-                const rawUploadPath = args.upload_path ||
-                    `/${pathModule.basename(localFilePath)}`;
-                const uploadPath = rawUploadPath.startsWith('/')
-                    ? rawUploadPath
-                    : `/${rawUploadPath}`;
-                const localStat = fs.statSync(localFilePath);
-                const files = collectUploadFiles(localFilePath);
-                if (localStat.isDirectory()) {
-                    if (files.length === 0) {
-                        logError(`Folder has no files to upload: ${localFilePath}`);
+                // skills save: read the local directory (default cwd) and ship its
+                // files inline — the inverse of `skills pull`. Client-side because
+                // only the local machine can walk a directory tree.
+                if (tool.name === 'skills_save') {
+                    const { collectSkillDir } = await import('./commands/skills-save.js');
+                    const dir = pathModule.resolve(primaryArgValue || '.');
+                    let collected;
+                    try {
+                        collected = collectSkillDir(dir);
+                    }
+                    catch (e) {
+                        logError(`skills save: ${e.message}`);
                         process.exit(1);
                     }
-                    info(`Uploading folder ${localFilePath} (${files.length} files)...`);
-                    const uploaded = [];
-                    for (const file of files) {
-                        const destination = pathModule.posix.join(uploadPath, file.relativePath);
-                        const result = await uploadToAiDrive(file.absolutePath, destination, override, workspace);
-                        if (result.status !== 'ok') {
-                            output(result);
-                            process.exit(1);
-                        }
-                        uploaded.push(destination);
+                    if (collected.sidecarOwner) {
+                        info(`Warning: ${dir} carries provenance for ${collected.sidecarOwner} — ` +
+                            `saving will fork this skill into your own catalog.`);
                     }
-                    output({
-                        status: 'ok',
-                        message: `Uploaded ${uploaded.length} files`,
-                        data: { workspace, root: uploadPath, files: uploaded },
-                    });
+                    // Collector-owned: `files` must be {path, content} read from the
+                    // local directory, so this assignment intentionally overrides any
+                    // --args-file value (the file-wins rule covers flag-shaped params
+                    // only, not CLI-populated ones).
+                    args.files = collected.files;
                 }
-                else {
-                    // Stream directly to AI Drive — single request, no blob middleman
-                    const result = await uploadToAiDrive(localFilePath, uploadPath, override, workspace);
-                    output(result);
+                // aidrive upload ergonomics: `gsk aidrive upload <path>` is the natural
+                // invocation and the dominant fumble — the bare path is an excess
+                // operand that Commander tolerates but never maps to an option, so the
+                // request otherwise reaches the API with no content and fails with a
+                // misleading "Missing file_content". When no explicit content source was
+                // given, adopt a path-like operand as --local_file (cmd.args[0] is the
+                // 'upload' action; later operands are candidate paths, directories
+                // skipped) so the streaming upload below handles it; if there is still
+                // no usable source, fail with an actionable message that names
+                // --local_file rather than the opaque backend error.
+                if (tool.name === 'aidrive' &&
+                    // args.action, not the positional: the action may arrive via
+                    // --args-file (sb-git's clone-url gate uses the same pattern).
+                    args.action === 'upload' &&
+                    !opts.local_file &&
+                    // args, not opts: file_content is a server param and may have
+                    // arrived via --args-file (merged into args above).
+                    !args.file_content) {
+                    // Skip the first operand only when it really is the action: with
+                    // the action arriving via --args-file, Commander binds a bare
+                    // path to the [action] positional slot, so cmd.args[0] is itself
+                    // a path candidate.
+                    const operandCandidates = primaryArgValue !== undefined && primaryArgValue === args.action
+                        ? invokedCmd.args.slice(1)
+                        : invokedCmd.args;
+                    const pathOperand = pickExistingUploadOperand(operandCandidates);
+                    if (pathOperand) {
+                        opts.local_file = pathOperand;
+                    }
+                    else {
+                        logError('upload needs a file source: use `--local_file <path>` for a ' +
+                            'local file (any size, binaries OK) or `--file_content <text>` ' +
+                            'for inline text. Example: gsk aidrive upload --local_file ' +
+                            './report.pdf --upload_path /report.pdf');
+                        process.exit(1);
+                    }
                 }
-                return;
-            }
-            const designAttachmentArgs = collectDesignAttachmentArgs(process.argv);
-            const isDesignAttachmentCommand = designAttachmentArgs.length > 0 &&
-                ((tool.name === 'create_task' && args.task_type === 'design') ||
-                    tool.name === 'task_continue');
-            if (isDesignAttachmentCommand) {
-                const uploaded = await uploadDesignAttachments(designAttachmentArgs, client);
-                const existing = Array.isArray(args.attachments)
-                    ? args.attachments
-                    : [];
-                args.attachments = [...existing, ...uploaded];
-                delete args.image;
-                delete args.file;
-            }
-            // Non-Design create_task --file keeps its CSV/Excel file_urls contract.
-            if (tool.name === 'create_task' &&
-                args.task_type !== 'design' &&
-                opts.file) {
-                const fileValues = Array.isArray(opts.file)
-                    ? opts.file
-                    : [opts.file];
-                const fileUrls = [];
-                for (const filePath of fileValues) {
-                    if (isLocalFilePath(filePath)) {
-                        // isLocalFilePath already verified existence via fs.existsSync
-                        const uploaded = await uploadLocalFile(filePath, client);
-                        const basename = pathModule.basename(filePath);
-                        const sep = uploaded.includes('?') ? '&' : '?';
-                        fileUrls.push(`${uploaded}${sep}original_name=${encodeURIComponent(basename)}`);
+                // aidrive: handle --local_file for the upload action.
+                // Stream the file directly to AI Drive via the dedicated tool_cli
+                // endpoint (POST /api/tool_cli/aidrive/upload) — no blob middleman.
+                if (tool.name === 'aidrive' &&
+                    args.action === 'upload' &&
+                    opts.local_file) {
+                    const localFilePath = opts.local_file;
+                    const override = !!opts.override;
+                    const workspace = args.workspace || 'personal';
+                    if (!fs.existsSync(localFilePath)) {
+                        logError(`File not found: ${localFilePath}`);
+                        process.exit(1);
                     }
-                    else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(filePath) ||
-                        filePath.startsWith('/api/')) {
-                        // Matches any URI scheme (http://, https://, aidrive://, etc.) or /api/ paths
-                        fileUrls.push(filePath);
+                    // args.upload_path is safe here: args = { ...opts } at line above, and
+                    // only local_file/override were deleted from args — upload_path is intact.
+                    const rawUploadPath = args.upload_path ||
+                        `/${pathModule.basename(localFilePath)}`;
+                    const uploadPath = rawUploadPath.startsWith('/')
+                        ? rawUploadPath
+                        : `/${rawUploadPath}`;
+                    const localStat = fs.statSync(localFilePath);
+                    const files = collectUploadFiles(localFilePath);
+                    if (localStat.isDirectory()) {
+                        if (files.length === 0) {
+                            logError(`Folder has no files to upload: ${localFilePath}`);
+                            process.exit(1);
+                        }
+                        info(`Uploading folder ${localFilePath} (${files.length} files)...`);
+                        const uploaded = [];
+                        for (const file of files) {
+                            const destination = pathModule.posix.join(uploadPath, file.relativePath);
+                            const result = await uploadToAiDrive(file.absolutePath, destination, override, workspace);
+                            if (result.status !== 'ok') {
+                                output(result);
+                                process.exit(1);
+                            }
+                            uploaded.push(destination);
+                        }
+                        output({
+                            status: 'ok',
+                            message: `Uploaded ${uploaded.length} files`,
+                            data: { workspace, root: uploadPath, files: uploaded },
+                        });
                     }
                     else {
-                        // Not a URL and not an existing local file — likely a typo
-                        logError(`File not found: ${filePath}`);
-                        process.exit(1);
+                        // Stream directly to AI Drive — single request, no blob middleman
+                        const result = await uploadToAiDrive(localFilePath, uploadPath, override, workspace);
+                        output(result);
                     }
+                    return;
                 }
-                // Merge with any --file_urls passed directly
-                const existing = Array.isArray(args.file_urls)
-                    ? args.file_urls
-                    : [];
-                args.file_urls = [...existing, ...fileUrls];
-                delete args.file; // CLI-only option, not a server parameter
-            }
-            // Resolve local file paths to uploaded URLs
-            const resolvedArgs = await resolveLocalFiles(args, client);
-            // The server owns the async-first default: create_task /
-            // task_continue return a submit stub ({status: "submitted",
-            // run_id, stream_url}) unless `--wait true` was passed. --attach
-            // upgrades the stub into a live SSE follow that exits with the
-            // run's terminal result — the work still executes server-side.
-            let result = await client.executeTool(tool.name, resolvedArgs);
-            const stubData = result.data;
-            if (attachTask &&
-                result.status === 'ok' &&
-                stubData &&
-                typeof stubData.stream_url === 'string' &&
-                (stubData.status === 'submitted' ||
-                    stubData.status === 'duplicate_submit_converged')) {
-                const meta = await client.attachGskTaskRun(stubData.stream_url);
-                const runStatus = String(meta.status || '');
-                const summary = meta.result_summary && typeof meta.result_summary === 'object'
-                    ? meta.result_summary
-                    : {};
-                result = {
-                    status: runStatus === 'succeeded' ? 'ok' : 'error',
-                    message: runStatus === 'succeeded'
-                        ? 'success'
-                        : `task ended with status ${runStatus || 'unknown'}`,
-                    data: {
-                        ...summary,
-                        run_id: stubData.run_id,
-                        run_status: runStatus,
-                    },
-                };
-            }
-            const isSbGitCloneUrl = tool.name === 'sb-git' &&
-                resolvedArgs.action === 'clone-url';
-            if (isSbGitCloneUrl &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                const data = result.data;
-                if (typeof data.url === 'string') {
-                    const before = data.url;
-                    const after = normalizeCloneUrlForGit(before);
-                    data.url = after;
-                    if (Array.isArray(data.commands)) {
-                        data.commands = data.commands.map(cmd => typeof cmd === 'string' ? cmd.replace(before, after) : cmd);
+                const designAttachmentArgs = collectDesignAttachmentArgs(process.argv);
+                const isDesignAttachmentCommand = designAttachmentArgs.length > 0 &&
+                    ((tool.name === 'create_task' && args.task_type === 'design') ||
+                        tool.name === 'task_continue');
+                if (isDesignAttachmentCommand) {
+                    const uploaded = await uploadDesignAttachments(designAttachmentArgs, client);
+                    const existing = Array.isArray(args.attachments)
+                        ? args.attachments
+                        : [];
+                    args.attachments = [...existing, ...uploaded];
+                    delete args.image;
+                    delete args.file;
+                }
+                // Non-Design create_task --file keeps its CSV/Excel file_urls contract.
+                if (tool.name === 'create_task' &&
+                    args.task_type !== 'design' &&
+                    opts.file) {
+                    const fileValues = Array.isArray(opts.file)
+                        ? opts.file
+                        : [opts.file];
+                    const fileUrls = [];
+                    for (const filePath of fileValues) {
+                        if (isLocalFilePath(filePath)) {
+                            // isLocalFilePath already verified existence via fs.existsSync
+                            const uploaded = await uploadLocalFile(filePath, client);
+                            const basename = pathModule.basename(filePath);
+                            const sep = uploaded.includes('?') ? '&' : '?';
+                            fileUrls.push(`${uploaded}${sep}original_name=${encodeURIComponent(basename)}`);
+                        }
+                        else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(filePath) ||
+                            filePath.startsWith('/api/')) {
+                            // Matches any URI scheme (http://, https://, aidrive://, etc.) or /api/ paths
+                            fileUrls.push(filePath);
+                        }
+                        else {
+                            // Not a URL and not an existing local file — likely a typo
+                            logError(`File not found: ${filePath}`);
+                            process.exit(1);
+                        }
                     }
+                    // Merge with any --file_urls passed directly
+                    const existing = Array.isArray(args.file_urls)
+                        ? args.file_urls
+                        : [];
+                    args.file_urls = [...existing, ...fileUrls];
+                    delete args.file; // CLI-only option, not a server parameter
                 }
-            }
-            // sb-git clone-url --execute: substitute placeholders + spawn
-            // `git clone` locally. Backend response stays placeholder-only
-            // (no secrets in stdout / logs); substitution + subprocess live
-            // here because they need in-process auth + access to git.
-            if (isSbGitCloneUrl &&
-                sbGitExecuteRequested &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                const globalOpts = getGlobalOptions();
-                const code = await executeCloneUrl({
-                    data: result.data,
-                    apiKey: globalOpts.apiKey || '',
-                    baseUrl: globalOpts.baseUrl,
-                    explicitDest: sbGitExecuteDest,
-                });
-                if (code !== 0)
-                    process.exit(code);
-                return;
-            }
-            // skills pull: decode the returned file rows + write the skill tree to
-            // disk (default ./<slug>, or --out <dir>). Client-side because the
-            // backend returns JSON, not a filesystem. Pull always materialises;
-            // the base64 blobs are dropped from the echoed result below.
-            if (tool.name === 'skills_pull' &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                const { writeSkillFiles } = await import('./commands/skills-pull.js');
-                const code = writeSkillFiles(result.data, skillsPullOut);
-                if (code !== 0)
-                    process.exit(code);
-                // Drop the (large, base64) file blobs from the echoed result — the
-                // user asked to write to disk, not to dump bytes to stdout.
-                const data = result.data;
-                delete data.files;
-                output(result);
-                return;
-            }
-            // skills sync: `--check` reports a diff without writing. Otherwise
-            // materialize the response via applySyncResponse (Task 5), looping
-            // while the server signals a truncated bundle (`complete: false`) —
-            // only the local machine holds the digest state across calls and
-            // can write the resulting file tree / symlinks.
-            if (tool.name === 'skills_sync' &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                if (skillsSyncCheck) {
+                // Resolve local file paths to uploaded URLs
+                const resolvedArgs = await resolveLocalFiles(args, client);
+                // The server owns the async-first default: create_task /
+                // task_continue return a submit stub ({status: "submitted",
+                // run_id, stream_url}) unless `--wait true` was passed. --attach
+                // upgrades the stub into a live SSE follow that exits with the
+                // run's terminal result — the work still executes server-side.
+                let result = await client.executeTool(tool.name, resolvedArgs);
+                const stubData = result.data;
+                if (attachTask &&
+                    result.status === 'ok' &&
+                    stubData &&
+                    typeof stubData.stream_url === 'string' &&
+                    (stubData.status === 'submitted' ||
+                        stubData.status === 'duplicate_submit_converged')) {
+                    const meta = await client.attachGskTaskRun(stubData.stream_url);
+                    const runStatus = String(meta.status || '');
+                    const summary = meta.result_summary && typeof meta.result_summary === 'object'
+                        ? meta.result_summary
+                        : {};
+                    result = {
+                        status: runStatus === 'succeeded' ? 'ok' : 'error',
+                        message: runStatus === 'succeeded'
+                            ? 'success'
+                            : `task ended with status ${runStatus || 'unknown'}`,
+                        data: {
+                            ...summary,
+                            run_id: stubData.run_id,
+                            run_status: runStatus,
+                        },
+                    };
+                }
+                const isSbGitCloneUrl = tool.name === 'sb-git' &&
+                    resolvedArgs.action === 'clone-url';
+                if (isSbGitCloneUrl &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
                     const data = result.data;
-                    for (const entry of data.skills) {
-                        const suffix = entry.code ? ` (${entry.code})` : '';
-                        info(`${entry.slug}: ${entry.action}${suffix}`);
+                    if (typeof data.url === 'string') {
+                        const before = data.url;
+                        const after = normalizeCloneUrlForGit(before);
+                        data.url = after;
+                        if (Array.isArray(data.commands)) {
+                            data.commands = data.commands.map(cmd => typeof cmd === 'string' ? cmd.replace(before, after) : cmd);
+                        }
                     }
-                    const dirty = data.skills.some(entry => entry.action !== 'unchanged');
-                    for (const entry of data.skills)
-                        delete entry.files;
+                }
+                // sb-git clone-url --execute: substitute placeholders + spawn
+                // `git clone` locally. Backend response stays placeholder-only
+                // (no secrets in stdout / logs); substitution + subprocess live
+                // here because they need in-process auth + access to git.
+                if (isSbGitCloneUrl &&
+                    sbGitExecuteRequested &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
+                    const globalOpts = getGlobalOptions();
+                    const code = await executeCloneUrl({
+                        data: result.data,
+                        apiKey: globalOpts.apiKey || '',
+                        baseUrl: globalOpts.baseUrl,
+                        explicitDest: sbGitExecuteDest,
+                    });
+                    if (code !== 0)
+                        process.exit(code);
+                    return;
+                }
+                // skills pull: decode the returned file rows + write the skill tree to
+                // disk (default ./<slug>, or --out <dir>). Client-side because the
+                // backend returns JSON, not a filesystem. Pull always materialises;
+                // the base64 blobs are dropped from the echoed result below.
+                if (tool.name === 'skills_pull' &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
+                    const { writeSkillFiles } = await import('./commands/skills-pull.js');
+                    const code = writeSkillFiles(result.data, skillsPullOut);
+                    if (code !== 0)
+                        process.exit(code);
+                    // Drop the (large, base64) file blobs from the echoed result — the
+                    // user asked to write to disk, not to dump bytes to stdout.
+                    const data = result.data;
+                    delete data.files;
                     output(result);
-                    if (dirty)
-                        process.exit(3);
                     return;
                 }
-                const { applySyncResponse, SyncAggregator } = await import('./commands/skills-sync.js');
-                const syncOpts = {
-                    storeDir: skillsSyncStoreDir,
-                    mountDir: skillsSyncMountDir,
-                };
-                let current = result;
-                // Fold every batch's outcome into deduped totals (see SyncAggregator):
-                // a server `error` row re-appears each batch, so concatenating would
-                // multi-count it and the summary + exit code would lie.
-                const agg = new SyncAggregator();
-                let iterations = 0;
-                for (;;) {
-                    const data = current.data;
-                    const applyResult = applySyncResponse(data, syncOpts);
-                    agg.add(applyResult, current.data.skills);
-                    if (data.complete !== false)
-                        break;
-                    iterations += 1;
-                    if (iterations >= 20) {
-                        logError('skills sync: exceeded 20 batches without completing — aborting');
-                        process.exit(1);
+                // skills sync: `--check` reports a diff without writing. Otherwise
+                // materialize the response via applySyncResponse (Task 5), looping
+                // while the server signals a truncated bundle (`complete: false`) —
+                // only the local machine holds the digest state across calls and
+                // can write the resulting file tree / symlinks.
+                if (tool.name === 'skills_sync' &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
+                    if (skillsSyncCheck) {
+                        const data = result.data;
+                        for (const entry of data.skills) {
+                            const suffix = entry.code ? ` (${entry.code})` : '';
+                            info(`${entry.slug}: ${entry.action}${suffix}`);
+                        }
+                        const dirty = data.skills.some(entry => entry.action !== 'unchanged');
+                        for (const entry of data.skills)
+                            delete entry.files;
+                        output(result);
+                        if (dirty)
+                            process.exit(3);
+                        return;
                     }
-                    current = await client.executeTool('skills_sync', {
-                        state: JSON.stringify(applyResult.state),
-                    });
-                    if (current.status !== 'ok' || !current.data) {
-                        logError(`skills sync: batch ${iterations} failed — ${current.message}`);
-                        process.exit(1);
+                    const { applySyncResponse, SyncAggregator } = await import('./commands/skills-sync.js');
+                    const syncOpts = {
+                        storeDir: skillsSyncStoreDir,
+                        mountDir: skillsSyncMountDir,
+                    };
+                    let current = result;
+                    // Fold every batch's outcome into deduped totals (see SyncAggregator):
+                    // a server `error` row re-appears each batch, so concatenating would
+                    // multi-count it and the summary + exit code would lie.
+                    const agg = new SyncAggregator();
+                    let iterations = 0;
+                    for (;;) {
+                        const data = current.data;
+                        const applyResult = applySyncResponse(data, syncOpts);
+                        agg.add(applyResult, current.data.skills);
+                        if (data.complete !== false)
+                            break;
+                        iterations += 1;
+                        if (iterations >= 20) {
+                            logError('skills sync: exceeded 20 batches without completing — aborting');
+                            process.exit(1);
+                        }
+                        current = await client.executeTool('skills_sync', {
+                            state: JSON.stringify(applyResult.state),
+                        });
+                        if (current.status !== 'ok' || !current.data) {
+                            logError(`skills sync: batch ${iterations} failed — ${current.message}`);
+                            process.exit(1);
+                        }
                     }
+                    info(`synced ${agg.appliedCount} updated / ${agg.removedCount} removed / ${agg.failedCount} failed`);
+                    // Emit the aggregated (all-batch, deduped) skill rows rather than only
+                    // the final batch's, stripping the base64 file blobs first.
+                    const aggregatedSkills = agg.skills;
+                    for (const entry of aggregatedSkills)
+                        delete entry.files;
+                    current.data.skills = aggregatedSkills;
+                    output(current);
+                    // A boot script runs `sync` every startup and keys off the exit
+                    // code; a per-slug failure (mount refused, write error, server
+                    // `error` row) must not read as success. Exit 4 (distinct from 3 =
+                    // `--check` found a diff, and 1 = the sync loop itself aborted) so
+                    // the caller can tell "some skills didn't materialize" from a clean
+                    // run. Exit 0 stays reserved for fully-clean.
+                    if (agg.failedCount > 0)
+                        process.exit(4);
+                    return;
                 }
-                info(`synced ${agg.appliedCount} updated / ${agg.removedCount} removed / ${agg.failedCount} failed`);
-                // Emit the aggregated (all-batch, deduped) skill rows rather than only
-                // the final batch's, stripping the base64 file blobs first.
-                const aggregatedSkills = agg.skills;
-                for (const entry of aggregatedSkills)
-                    delete entry.files;
-                current.data.skills = aggregatedSkills;
-                output(current);
-                // A boot script runs `sync` every startup and keys off the exit
-                // code; a per-slug failure (mount refused, write error, server
-                // `error` row) must not read as success. Exit 4 (distinct from 3 =
-                // `--check` found a diff, and 1 = the sync loop itself aborted) so
-                // the caller can tell "some skills didn't materialize" from a clean
-                // run. Exit 0 stays reserved for fully-clean.
-                if (agg.failedCount > 0)
-                    process.exit(4);
-                return;
-            }
-            // If -o was specified and tool succeeded, download the output file.
-            // Skip for create_task — it has its own export logic below.
-            if (tool.name !== 'create_task' &&
-                outputFilePath &&
-                outputFileKeys.length > 0 &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                const fileUrl = extractFileUrl(result.data, outputFileKeys);
-                if (fileUrl) {
-                    const localPath = await downloadToFile(fileUrl, outputFilePath, client);
-                    result.data.local_path = localPath;
-                }
-                else {
-                    info('Warning: Could not find a file URL in the result to download');
+                // If -o was specified and tool succeeded, download the output file.
+                // Skip for create_task — it has its own export logic below.
+                if (tool.name !== 'create_task' &&
+                    outputFilePath &&
+                    outputFileKeys.length > 0 &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
+                    const fileUrl = extractFileUrl(result.data, outputFileKeys);
+                    if (fileUrl) {
+                        const localPath = await downloadToFile(fileUrl, outputFilePath, client);
+                        result.data.local_path = localPath;
+                    }
+                    else {
+                        info('Warning: Could not find a file URL in the result to download');
+                    }
                 }
-            }
-            // create_task -o: export artifact (pptx/docx/xlsx) after task completes
-            if (tool.name === 'create_task' &&
-                outputFilePath &&
-                result.status === 'ok' &&
-                result.data &&
-                typeof result.data === 'object') {
-                const data = result.data;
-                const projectId = data.project_id;
-                // args.type is the value actually sent to the API: the positional
-                // is copied into args and --args-file may override it (file wins),
-                // so the export must key on the merged view, never the positional.
-                const taskType = args.type;
-                if (projectId && taskType) {
-                    info(`Exporting ${taskType} artifact...`);
-                    try {
-                        const exportResult = await client.exportArtifact(projectId, taskType);
-                        if (exportResult.status === 'ok' && exportResult.data) {
-                            const expData = exportResult.data;
-                            const downloadUrl = expData.download_url;
-                            if (downloadUrl) {
-                                const localPath = await downloadToFile(downloadUrl, outputFilePath, client);
-                                data.local_path = localPath;
-                                data.export_format = expData.format;
+                // create_task -o: export artifact (pptx/docx/xlsx) after task completes
+                if (tool.name === 'create_task' &&
+                    outputFilePath &&
+                    result.status === 'ok' &&
+                    result.data &&
+                    typeof result.data === 'object') {
+                    const data = result.data;
+                    const projectId = data.project_id;
+                    // args.type is the value actually sent to the API: the positional
+                    // is copied into args and --args-file may override it (file wins),
+                    // so the export must key on the merged view, never the positional.
+                    const taskType = args.type;
+                    if (projectId && taskType) {
+                        info(`Exporting ${taskType} artifact...`);
+                        try {
+                            const exportResult = await client.exportArtifact(projectId, taskType);
+                            if (exportResult.status === 'ok' && exportResult.data) {
+                                const expData = exportResult.data;
+                                const downloadUrl = expData.download_url;
+                                if (downloadUrl) {
+                                    const localPath = await downloadToFile(downloadUrl, outputFilePath, client);
+                                    data.local_path = localPath;
+                                    data.export_format = expData.format;
+                                }
+                            }
+                            else {
+                                info(`Warning: Export not available — ${exportResult.message || 'unknown error'}`);
                             }
                         }
-                        else {
-                            info(`Warning: Export not available — ${exportResult.message || 'unknown error'}`);
+                        catch (exportErr) {
+                            info(`Warning: Export failed — ${exportErr.message}`);
                         }
                     }
-                    catch (exportErr) {
-                        info(`Warning: Export failed — ${exportErr.message}`);
-                    }
                 }
+                // Media generation payloads print compact + a stderr field summary
+                // so agent-side `grep | head` filters can't lose the URLs/task_id
+                // (the fabricated-URL incident behind PR #41690) — see
+                // mediaSummary.ts for the full rationale.
+                for (const line of mediaSummaryLines(tool.name, result)) {
+                    info(line);
+                }
+                // web_search payloads are large and agent-consumed — indent-2 here
+                // is pure token overhead on every SAS/Claw search
+                output(result, {
+                    compact: tool.name === 'web_search' || Boolean(mediaItemsKeyFor(tool.name)),
+                });
             }
-            // Media generation payloads print compact + a stderr field summary
-            // so agent-side `grep | head` filters can't lose the URLs/task_id
-            // (the fabricated-URL incident behind PR #41690) — see
-            // mediaSummary.ts for the full rationale.
-            for (const line of mediaSummaryLines(tool.name, result)) {
-                info(line);
+            catch (err) {
+                logError(err.message);
+                process.exit(1);
             }
-            // web_search payloads are large and agent-consumed — indent-2 here
-            // is pure token overhead on every SAS/Claw search
-            output(result, {
-                compact: tool.name === 'web_search' || Boolean(mediaItemsKeyFor(tool.name)),
-            });
         }
-        catch (err) {
-            logError(err.message);
-            process.exit(1);
+    };
+    cmd.action((primaryArgValue, opts) => runToolInvocation(primaryArgValue, opts));
+    // Per-action subcommands (issue #51377) — see the actionViews comment at
+    // the top of this function: a wrong-action flag now fails at parse time
+    // with a did-you-mean, and `gsk teams send --help` shows only that
+    // action's flags, while the flag-free parent still handles the bare
+    // invocation (action listing), --args-file carrying the action, and
+    // unknown action names (surfaced server-side).
+    if (actionViews) {
+        const allActionNames = actionViews.map(view => view.name);
+        for (const view of actionViews) {
+            const sub = cmd.command(view.name).description(view.description);
+            for (const paramName of view.parameters) {
+                addSchemaOption(sub, paramName, props[paramName], {
+                    // Same relaxation as the union path: with --args-file on the
+                    // command line, required params may live in the file, which
+                    // Commander cannot see at parse time.
+                    isRequired: argsFileInvoked
+                        ? false
+                        : view.required.includes(paramName),
+                    shortAlias: aliases[paramName],
+                    injectedDefault: tool.cli.group === 'vd' && paramName === 'vd_project_id'
+                        ? vdProjectIdDefault
+                        : undefined,
+                    description: actionScopedDescription(props[paramName].description || paramName, view.name, allActionNames),
+                });
+            }
+            if (hasAttachmentsParam && view.parameters.includes('attachments')) {
+                sub.option('--attach <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
+                sub.option('--attachment <values...>', 'Attach local files or URLs (alias for --attachments; repeatable)');
+            }
+            sub.option('--args-file <path>', 'Read arguments from a JSON object file ("-" = stdin). File keys ' +
+                'override flag values. Use for rich text (strings containing $, ' +
+                'quotes, newlines) instead of double-quoted flags. Server ' +
+                'parameters only — CLI-only options must still be passed as flags.');
+            if (outputFileKeys.length > 0) {
+                sub.option('-o, --output-file <path>', 'Download the generated file to a local path');
+            }
+            sub.action((opts) => runToolInvocation(view.name, opts, sub));
         }
-    });
+    }
 }
 // ============================================
 // Built-in Commands
@@ -2085,8 +2165,8 @@ async function phoneCallAction(recipient, opts, invokedAs) {
             info('=== Call Dispatched (async) ===');
             info(`  Recipient:  ${data.recipient || recipient}`);
             info(`  Project ID: ${data.project_id}`);
-            info(`  Poll:  gsk call-status ${data.project_id}`);
-            info(`  Stop:  gsk call-hangup ${data.project_id}`);
+            info(`  Poll:  gsk telephony call status ${data.project_id}`);
+            info(`  Stop:  gsk telephony call hangup ${data.project_id}`);
             output(result);
             return;
         }
@@ -2357,6 +2437,41 @@ async function main() {
     const forceRefresh = globalOpts.refresh || false;
     // Try to load tools from cache
     let tools = forceRefresh ? null : loadToolsCache(baseUrl);
+    // Needed both for the stale-cache check and for dynamic registration below.
+    const vdProjectId = resolveVdProjectId();
+    // Stale-cache self-heal (#51775): the server omits gatekeeper-gated tools
+    // per user, so a cached tree written before a gate flipped ON rejects the
+    // newly enabled command for up to the cache TTL. When argv clearly cannot
+    // resolve against the cached tree, drop the cache and take the fetch
+    // branch below — one manifest GET instead of a 24h blind window.
+    // When the heal path drops the cache, keep the stale tree as a fallback:
+    // a failed manifest GET must not leave the invocation with ZERO dynamic
+    // commands (strictly worse than the stale cache it replaced).
+    let staleFallbackTools = null;
+    if (tools && globalOpts.apiKey) {
+        let missing = null;
+        try {
+            const { operands } = program.parseOptions(process.argv.slice(2));
+            const index = collectToolCommandTokens(tools, Boolean(vdProjectId));
+            // phone-call / call-for-me dial by DEFAULT subcommand, so their second
+            // token may be a recipient — never provably a miss. (`telephony call
+            // <recipient>` is level-3 and outside the two-level check.)
+            addRegisteredCommands(index, program.commands, [
+                'phone-call',
+                'call-for-me',
+            ]);
+            missing = staleCacheMissingToken(index, operands);
+        }
+        catch {
+            // Conservative: any hiccup in the pre-parse means we keep the cache.
+        }
+        if (missing) {
+            debug(`'${missing}' is not in the cached command tree — bypassing the ` +
+                'tools cache and refetching the manifest (stale-cache self-heal)');
+            staleFallbackTools = tools;
+            tools = null;
+        }
+    }
     if (tools) {
         debug(`Loaded ${tools.length} tools from cache`);
     }
@@ -2396,12 +2511,18 @@ async function main() {
             debug('No API key available, skipping tool fetch');
         }
     }
+    // Self-heal refetch failed (network/auth): fall back to the stale cache
+    // so this invocation still registers every previously known command.
+    if (!tools && staleFallbackTools) {
+        debug('Manifest refetch failed — falling back to the cached (possibly ' +
+            'stale) command tree');
+        tools = staleFallbackTools;
+    }
     // Register dynamic tool commands
     // Skip phone_call — the hardcoded `phone-call` command (dial default
     // subcommand) handles dialing with streaming UX the generic handler lacks.
     // Hide the `vd` subcommand group entirely unless the user has opted in
     // via config.vd_project_id or GSK_VD_PROJECT_ID env var.
-    const vdProjectId = resolveVdProjectId();
     if (tools) {
         for (const tool of tools) {
             if (tool.name === 'phone_call')