@agentworkforce/cli 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -9,11 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `agentworkforce agent` now records launch metadata for direct harness
+  launches; opt out with `--no-launch-metadata` or
+  `AGENTWORKFORCE_LAUNCH_METADATA=0`.
 - `agentworkforce create` now opens `persona-maker@best`, supports `--to` and
   `--save-default`, and passes `TARGET_DIR` / `CREATE_MODE` persona inputs.
 - Persona source config supports `defaultCreateTarget` for the implicit create target.
 - `--version`/`-v` now prints the CLI package version.
 
+## [0.12.0] - 2026-05-08
+
+### Released
+
+- v0.12.0
+
+## [0.11.0] - 2026-05-08
+
+### Released
+
+- v0.11.0
+
 ## [0.10.0] - 2026-05-08
 
 ### Released

package/README.md

@@ -6,8 +6,8 @@ built-in one from `/personas/`, or an installed/local one that extends a lower
 source.
 
 ```
-agentworkforce create [--to <target>] [--save-default]
-agentworkforce agent <persona>[@<tier>]
+agentworkforce create [--to <target>] [--save-default] [--install-in-repo] [--no-launch-metadata]
+agentworkforce agent [--install-in-repo] [--no-launch-metadata] <persona>[@<tier>]
 agentworkforce list [flags]
 agentworkforce show <persona>[@<tier>]
 agentworkforce install [flags] <pkg|path>
@@ -68,7 +68,7 @@ Unknown persona prints the full catalog with each entry's origin.
 ## Create
 
 ```
-agentworkforce create [--to <target>] [--save-default] [--install-in-repo]
+agentworkforce create [--to <target>] [--save-default] [--install-in-repo] [--no-launch-metadata]
 ```
 
 `create` is the persona-authoring entry point. It runs `persona-maker@best`
@@ -860,7 +860,7 @@ persona session, add it to the persona's `mcpServers` block.
 ## Interactive
 
 ```sh
-agentworkforce agent [--install-in-repo] <persona>[@<tier>]
+agentworkforce agent [--install-in-repo] [--no-launch-metadata] <persona>[@<tier>]
 ```
 
 By default, claude and opencode sessions run inside a sandbox mount — see
@@ -887,10 +887,34 @@ By default, claude and opencode sessions run inside a sandbox mount — see
      initial argument.
 5. Runs the skill cleanup command on exit, regardless of exit status. In
    stage-dir mode this is a single `rm -rf <stage-dir>`.
-6. Propagates the harness's exit code.
+6. Records launch metadata for the session and refreshes harness session logs
+   while the child runs, then once more after exit. The harness is still
+   launched directly.
+7. Propagates the harness's exit code.
 
 Signals (SIGINT, SIGTERM) are forwarded to the child.
 
+### Launch Metadata
+
+Persona launches record metadata by default when the installed backend supports
+launcher metadata. AgentWorkforce records:
+`agentworkforce=1`, `persona=<id>`, `personaTier=<tier>`,
+`personaVersion=<sha256>`, and `personaSource=<cwd|user|dir:n|library>`.
+`personaVersion` is the SHA-256 of the fully resolved persona spec after
+cascade/extends merge and before prompt input substitution.
+
+Opt out for one launch:
+
+```sh
+agentworkforce agent --no-launch-metadata code-reviewer@best
+```
+
+Opt out through the environment:
+
+```sh
+AGENTWORKFORCE_LAUNCH_METADATA=0 agentworkforce agent code-reviewer@best
+```
+
 ## Skill staging
 
 By default, interactive `claude` sessions stage skills under the user's home

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type Harness, type PersonaMount, type PersonaSelection, type SidecarMdMode } from '@agentworkforce/workload-router';
+import { type PickCandidate } from './persona-picker.js';
 export declare const CLI_VERSION: string;
 export declare const CREATE_SELECTOR = "persona-maker@best";
 /**
@@ -140,9 +141,29 @@ export interface PersonaInstallArgs {
     overwrite: boolean;
 }
 export declare function parseInstallArgs(args: readonly string[]): PersonaInstallArgs;
+/**
+ * Enumerate persona candidates for the picker. Local overrides win over the
+ * built-in catalog when ids collide; the picker only needs the projection
+ * fields ({@link PickCandidate}), not full specs.
+ */
+export declare function buildPickCandidates(): PickCandidate[];
+/**
+ * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
+ * empty input or non-y answer. Used by `pick` when the picker reports
+ * no-match in an interactive session.
+ *
+ * Test seam: callers can inject `read` so the prompt path is exercisable
+ * without a real TTY.
+ */
+export declare function promptYesNoSync(question: string, opts?: {
+    isTTY?: boolean;
+    write?: (chunk: string) => void;
+    read?: () => string | undefined;
+}): boolean;
 export declare function main(): Promise<void>;
 export interface AgentFlags {
     installInRepo: boolean;
+    noLaunchMetadata: boolean;
 }
 export interface CreateFlags extends AgentFlags {
     to?: string;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiBA,OAAO,EAQL,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAIrB,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AA6BzC,OAAO,EAAe,KAAK,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAqIvF,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAmDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AAyJD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,gFAUzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,2JAiBjC,CAAC;AAEX,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GAAG,sBAAsB,CAqBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,GAC1B;IAAE,OAAO,CAAC,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqDjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,MAAM,GACjB,MAAM,CAkBR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAipBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAqmBD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,EAAE,CAmBrD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IACJ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAC5B,GACL,OAAO,CAWT;AAiGD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAiE1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CA4BA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CAgEA"}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -9,8 +9,10 @@ import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, resolveSid
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
 import { launchOnMount, readAgentDotfiles } from '@relayfile/local-mount';
 import ora from 'ora';
+import { startLaunchMetadataRecording } from './launch-metadata.js';
 import { buildPersonaSourceDirectories, defaultCwdPersonaDir, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
 import { installPersonas } from './persona-install.js';
+import { pickPersona } from './persona-picker.js';
 const USAGE = `Usage: agentworkforce <command> [args...]
 
 Commands:
@@ -26,6 +28,8 @@ Commands:
                         --save-default      Persist --to as defaultCreateTarget in
                                             ~/.agentworkforce/workforce/config.json.
                         --install-in-repo   Same behavior as agent.
+                        --no-launch-metadata
+                                            Same behavior as agent.
   agent [flags] <persona>[@<tier>]
                       Run a persona. Tier one of: ${PERSONA_TIERS.join(' | ')}
                       (default: best-value). Drops into an interactive harness
@@ -46,6 +50,10 @@ Commands:
                                             are hidden from the session. Codex
                                             sessions never mount and ignore
                                             this flag.
+                        --no-launch-metadata
+                                            Disable launch metadata recording.
+                                            Also disabled by
+                                            AGENTWORKFORCE_LAUNCH_METADATA=0.
   list [flags]        List available personas from the cascade (cwd →
                       configured persona dirs → library). By default shows
                       one row per persona at the recommended tier for its
@@ -85,6 +93,13 @@ Commands:
                       1-based configurable position.
   harness check       Probe which harnesses (claude, codex, opencode) are
                       installed and runnable on this machine.
+  pick "<task>"       Pick the best-fit persona for a free-text task description
+                      using a cheap LLM call (Claude Haiku via the local
+                      \`claude\` CLI). Prints the matched persona id to stdout
+                      on success. On low confidence, prompts (TTY) to launch
+                      persona-maker with the task as input, or exits non-zero
+                      (non-TTY) with a hint.
+                      Exit codes: 0 match, 2 no match, 3 picker unavailable.
 
 Options:
   -h, --help          Show this help text.
@@ -109,6 +124,8 @@ Examples:
   agentworkforce sources list
   agentworkforce sources add ../my-personas --position 1
   agentworkforce harness check
+  agentworkforce pick "review this PR for security issues"
+  agentworkforce agent "$(agentworkforce pick "fix the flaky test in foo.test.ts")"
 `;
 function die(msg, withUsage = true) {
     process.stderr.write(`${msg}\n`);
@@ -165,7 +182,10 @@ function parseSelector(sel) {
     if ('error' in result)
         die(result.error, false);
     const kind = local.byId.has(key) ? 'local' : 'repo';
-    return { kind, spec: result, tier };
+    if (kind === 'local') {
+        return { kind, source: local.sources.get(result.id) ?? 'cwd', spec: result, tier };
+    }
+    return { kind, source: 'library', spec: result, tier };
 }
 /**
  * Resolve the `<harness>` placeholder used in persona systemPrompts.
@@ -613,7 +633,7 @@ export function decideCleanMode(harness, installInRepo = false) {
     }
     return { useClean: false };
 }
-async function runInteractive(selection, options = {}) {
+async function runInteractive(selection, options) {
     const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
     const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
     const effectiveSelection = {
@@ -657,6 +677,14 @@ async function runInteractive(selection, options = {}) {
     const ctx = useSelection(effectiveSelection, installRoot !== undefined ? { installRoot } : {});
     const { install } = ctx;
     process.stderr.write(`→ ${personaId} [${tier}] via ${runtime.harness} (${runtime.model})\n`);
+    const startLaunchMetadataForLaunch = (cwd = process.cwd()) => startLaunchMetadataRecording({
+        selection: effectiveSelection,
+        personaSpec: options.personaSpec,
+        personaSource: options.personaSource,
+        cwd,
+        noLaunchMetadata: options.noLaunchMetadata,
+        env: process.env
+    });
     const inputEnv = inputResolution.values;
     const callerEnv = { ...process.env, ...inputEnv };
     const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
@@ -754,6 +782,7 @@ async function runInteractive(selection, options = {}) {
     // copied in from the real repo nor synced back on exit.
     if (useClean && sessionRoot) {
         const mountDir = sessionMountDir(sessionRoot);
+        let launchMetadata;
         // Anything we materialize into the mount via onBeforeLaunch must be
         // hidden from the mount-mirror in both directions: without this, any
         // opencode.json already present in the real repo would be copied into
@@ -874,7 +903,7 @@ async function runInteractive(selection, options = {}) {
                         process.stderr.write(`✓ ${message}\n`);
                     }
                 },
-                onBeforeLaunch: (dir) => {
+                onBeforeLaunch: async (dir) => {
                     // Run before install / configFile writes so the freshly written
                     // files (e.g. `.opencode/`, `opencode.json`) aren't yet present
                     // when we run `git ls-files` to pick skip-worktree candidates —
@@ -897,6 +926,7 @@ async function runInteractive(selection, options = {}) {
                         const body = buildSidecarBody(resolvedSidecar, process.cwd());
                         writeFileSync(join(dir, resolvedSidecar.mountFile), body, 'utf8');
                     }
+                    launchMetadata = await startLaunchMetadataForLaunch(dir);
                 }
             });
             return result.exitCode;
@@ -931,6 +961,7 @@ async function runInteractive(selection, options = {}) {
                 syncSpinner.stop();
                 syncSpinner = undefined;
             }
+            await launchMetadata?.stop();
             process.removeListener('SIGINT', forceExitHandler);
             // When the install ran inside the mount, its cleanup paths are
             // mount-relative (e.g. `.skills/<name>`, `skills/<name>`) and
@@ -944,6 +975,7 @@ async function runInteractive(selection, options = {}) {
             removeSessionRoot(sessionRoot);
         }
     }
+    const launchMetadata = await startLaunchMetadataForLaunch();
     return new Promise((resolve) => {
         let settled = false;
         const finish = (code) => {
@@ -952,7 +984,7 @@ async function runInteractive(selection, options = {}) {
             settled = true;
             runCleanup(install.cleanupCommand, install.cleanupCommandString);
             removeSessionRoot(sessionRoot);
-            resolve(code);
+            void launchMetadata.stop().finally(() => resolve(code));
         };
         const child = spawn(spec.bin, finalArgs, {
             stdio: 'inherit',
@@ -1750,10 +1782,136 @@ async function runAgentSelector(selector, flags, inputValues) {
         ...(inputValues ? { inputValues } : {})
     };
     const code = await runInteractive(selection, {
-        installInRepo: flags.installInRepo
+        installInRepo: flags.installInRepo,
+        noLaunchMetadata: flags.noLaunchMetadata,
+        personaSpec: target.spec,
+        personaSource: target.source
     });
     process.exit(code);
 }
+/**
+ * Enumerate persona candidates for the picker. Local overrides win over the
+ * built-in catalog when ids collide; the picker only needs the projection
+ * fields ({@link PickCandidate}), not full specs.
+ */
+export function buildPickCandidates() {
+    const byId = new Map();
+    for (const spec of Object.values(personaCatalog)) {
+        byId.set(spec.id, {
+            id: spec.id,
+            intent: spec.intent,
+            tags: [...spec.tags],
+            description: spec.description
+        });
+    }
+    for (const [id, spec] of local.byId.entries()) {
+        byId.set(id, {
+            id,
+            intent: spec.intent,
+            tags: [...spec.tags],
+            description: spec.description
+        });
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
+ * empty input or non-y answer. Used by `pick` when the picker reports
+ * no-match in an interactive session.
+ *
+ * Test seam: callers can inject `read` so the prompt path is exercisable
+ * without a real TTY.
+ */
+export function promptYesNoSync(question, opts = {}) {
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+    if (!isTTY)
+        return false;
+    const write = opts.write ?? ((chunk) => {
+        process.stderr.write(chunk);
+    });
+    write(question);
+    const answer = opts.read ? opts.read() : readLineFromStdinSync();
+    if (!answer)
+        return false;
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}
+function readLineFromStdinSync() {
+    const buf = Buffer.alloc(256);
+    let line = '';
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            return line || undefined;
+        }
+        if (n <= 0)
+            return line || undefined;
+        const chunk = buf.subarray(0, n).toString('utf8');
+        const newlineIdx = chunk.indexOf('\n');
+        if (newlineIdx === -1) {
+            line += chunk;
+            continue;
+        }
+        line += chunk.slice(0, newlineIdx);
+        return line;
+    }
+}
+async function runPick(args) {
+    const positional = [];
+    for (const arg of args) {
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce pick "<task description>"\n' +
+                '  Prints the best-fit persona id to stdout. On low confidence, prompts to\n' +
+                '  open persona-maker (TTY) or exits 2 (non-TTY). Exits 3 if `claude` is\n' +
+                '  not installed.\n');
+            process.exit(0);
+        }
+        positional.push(arg);
+    }
+    if (positional.length === 0) {
+        die('pick: missing task description. Usage: agentworkforce pick "<task>"');
+    }
+    if (positional.length > 1) {
+        die(`pick: expected a single quoted task description, got ${positional.length} arguments. ` +
+            `Did you forget to quote the task? Try: agentworkforce pick "${positional.join(' ')}"`);
+    }
+    const task = positional[0].trim();
+    if (!task) {
+        die('pick: task description is empty.');
+    }
+    const candidates = buildPickCandidates();
+    const result = pickPersona(task, candidates);
+    if (result.kind === 'match') {
+        process.stderr.write(`• picked ${result.personaId} (${result.confidence}): ${result.reason}\n`);
+        process.stdout.write(`${result.personaId}\n`);
+        process.exit(0);
+    }
+    if (result.kind === 'picker-unavailable') {
+        process.stderr.write(`pick: ${result.message}\n`);
+        process.exit(3);
+    }
+    // no-match
+    process.stderr.write(`pick: no close persona match — ${result.reason}\n`);
+    const wantsCreate = promptYesNoSync('Open persona-maker to scaffold a new persona for this task? [y/N] ');
+    if (!wantsCreate) {
+        process.stderr.write('Try: agentworkforce list   # to browse existing personas\n' +
+            '     agentworkforce create  # to author a new persona\n');
+        process.exit(2);
+    }
+    const target = resolveCreateTarget(undefined);
+    ensureCreateTargetDir(target);
+    const inputValues = {
+        ...buildCreateInputValues(target),
+        TASK_DESCRIPTION: task
+    };
+    await runAgentSelector(CREATE_SELECTOR, { installInRepo: false, noLaunchMetadata: false }, inputValues);
+    // runAgentSelector terminates via process.exit; this satisfies TS's
+    // reachable-end-point check for the `Promise<never>` return type.
+    process.exit(0);
+}
 export async function main() {
     const argv = process.argv.slice(2);
     const [subcommand, ...rest] = argv;
@@ -1794,6 +1952,9 @@ export async function main() {
         const { flags, selector, inputValues } = parseCreateArgs(rest);
         await runAgentSelector(selector, flags, inputValues);
     }
+    if (subcommand === 'pick') {
+        await runPick(rest);
+    }
     if (subcommand !== 'agent') {
         die(`Unknown subcommand "${subcommand}".`);
     }
@@ -1807,7 +1968,7 @@ export async function main() {
     await runAgentSelector(selector, flags);
 }
 export function parseAgentArgs(args) {
-    const flags = { installInRepo: false };
+    const flags = { installInRepo: false, noLaunchMetadata: false };
     const positional = [];
     let seenDoubleDash = false;
     for (const arg of args) {
@@ -1823,6 +1984,10 @@ export function parseAgentArgs(args) {
             flags.installInRepo = true;
             continue;
         }
+        if (arg === '--no-launch-metadata') {
+            flags.noLaunchMetadata = true;
+            continue;
+        }
         if (arg === '-h' || arg === '--help') {
             process.stdout.write(USAGE);
             process.exit(0);
@@ -1832,7 +1997,7 @@ export function parseAgentArgs(args) {
     return { flags, positional };
 }
 export function parseCreateArgs(args) {
-    const flags = { installInRepo: false, saveDefault: false };
+    const flags = { installInRepo: false, noLaunchMetadata: false, saveDefault: false };
     let seenDoubleDash = false;
     const positional = [];
     const valueOf = (i, flag) => {
@@ -1856,6 +2021,10 @@ export function parseCreateArgs(args) {
             flags.installInRepo = true;
             continue;
         }
+        if (arg === '--no-launch-metadata') {
+            flags.noLaunchMetadata = true;
+            continue;
+        }
         if (arg === '--to') {
             flags.to = valueOf(i, arg);
             i += 1;
@@ -1866,7 +2035,7 @@ export function parseCreateArgs(args) {
             continue;
         }
         if (arg === '-h' || arg === '--help') {
-            process.stdout.write('Usage: agentworkforce create [--to <cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo]\n');
+            process.stdout.write('Usage: agentworkforce create [--to <cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo] [--no-launch-metadata]\n');
             process.exit(0);
         }
         positional.push(arg);