@phnx-labs/agents-cli 1.20.0 → 1.20.4

package/dist/lib/cli-resources.js

@@ -7,12 +7,109 @@
  * but unlike skills/commands/hooks, CLI resources are NOT copied into per-agent
  * version homes — they install binaries onto the host PATH. The relationship is
  * "Brewfile-style": declare once in ~/.agents/cli/, install on any new machine.
+ *
+ * Security: every field that becomes a child-process argument is validated
+ * against a strict allowlist and dispatched via spawnSync with an argv array.
+ * Nothing here ever runs through a shell — manifests can come from project repos
+ * or pulled extras, so anything that would let a manifest author smuggle in
+ * `;`, `$(...)`, backticks, redirects, or pipe operators is a remote-code-
+ * execution sink.
  */
 import * as fs from 'fs';
-import { execSync, spawnSync } from 'child_process';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
 import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
+// ─── Validation primitives ───────────────────────────────────────────────────
+/** Token allowed inside `check:` strings — letters, digits, underscore, dot, slash, dash. */
+const SAFE_CHECK_TOKEN = /^[a-zA-Z0-9_./-]+$/;
+/** npm package name with optional scope and optional version/tag. */
+const NPM_PACKAGE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(@[a-zA-Z0-9._-]+)?$/;
+/** Homebrew formula name (and optional tap prefix). */
+const BREW_FORMULA = /^([a-z0-9][a-z0-9_.-]*\/[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.+-]*$/;
+/** Path segment inside a tarball — no leading slash, no `..`, no shell metas. */
+const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9_./-]+$/;
+function assertSafeCheckToken(tok) {
+    if (!SAFE_CHECK_TOKEN.test(tok)) {
+        throw new Error(`check contains unsafe token: ${JSON.stringify(tok)}`);
+    }
+}
+function assertNpmPackage(name) {
+    if (!NPM_PACKAGE.test(name)) {
+        throw new Error(`npm package name is not allowlisted: ${JSON.stringify(name)}`);
+    }
+}
+function assertBrewFormula(name) {
+    if (!BREW_FORMULA.test(name)) {
+        throw new Error(`brew formula name is not allowlisted: ${JSON.stringify(name)}`);
+    }
+}
+function assertHttpsUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`url is not parseable: ${JSON.stringify(url)}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`url must use https:// (got ${parsed.protocol}): ${JSON.stringify(url)}`);
+    }
+}
+function assertSafePathSegment(seg) {
+    if (!SAFE_PATH_SEGMENT.test(seg) || seg.startsWith('/') || seg.split('/').includes('..')) {
+        throw new Error(`extract path is not allowlisted: ${JSON.stringify(seg)}`);
+    }
+}
 // ─── Parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Parse a `check:` field into a CheckSpec. Accepts either a structured object
+ * (`{ kind: 'which'|'version', cmd, args? }`) or a legacy whitespace-separated
+ * string. String form is split on whitespace and each token is validated against
+ * SAFE_CHECK_TOKEN — manifests cannot smuggle in shell metacharacters.
+ */
+export function parseCheckSpec(raw, defaultName) {
+    if (raw == null) {
+        assertSafeCheckToken(defaultName);
+        return { kind: 'version', cmd: defaultName, args: ['--version'] };
+    }
+    if (typeof raw === 'string') {
+        const tokens = raw.trim().split(/\s+/).filter((t) => t.length > 0);
+        if (tokens.length === 0) {
+            assertSafeCheckToken(defaultName);
+            return { kind: 'version', cmd: defaultName, args: ['--version'] };
+        }
+        for (const tok of tokens)
+            assertSafeCheckToken(tok);
+        const [cmd, ...args] = tokens;
+        return args.length === 0 ? { kind: 'which', cmd } : { kind: 'version', cmd, args };
+    }
+    if (typeof raw === 'object') {
+        const r = raw;
+        const kind = r.kind;
+        if (kind !== 'which' && kind !== 'version') {
+            throw new Error(`check.kind must be "which" or "version" (got ${JSON.stringify(kind)})`);
+        }
+        if (typeof r.cmd !== 'string' || !r.cmd.trim()) {
+            throw new Error('check.cmd must be a non-empty string');
+        }
+        const cmd = r.cmd.trim();
+        assertSafeCheckToken(cmd);
+        if (kind === 'which')
+            return { kind: 'which', cmd };
+        const args = Array.isArray(r.args) ? r.args : [];
+        const safeArgs = [];
+        for (const a of args) {
+            if (typeof a !== 'string')
+                throw new Error('check.args entries must be strings');
+            assertSafeCheckToken(a);
+            safeArgs.push(a);
+        }
+        return { kind: 'version', cmd, args: safeArgs };
+    }
+    throw new Error('check must be a string or an object with { kind, cmd, args? }');
+}
 /**
  * Parse a single CLI manifest from its YAML contents.
  * Returns a manifest on success; throws on schema violations so callers can
@@ -24,11 +121,10 @@ export function parseCliManifest(contents, opts) {
         throw new Error('manifest must be a YAML object');
     }
     const name = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : opts.name;
+    assertSafeCheckToken(name);
     const description = typeof raw.description === 'string' ? raw.description : undefined;
     const homepage = typeof raw.homepage === 'string' ? raw.homepage : undefined;
-    const check = typeof raw.check === 'string' && raw.check.trim()
-        ? raw.check.trim()
-        : `${name} --version`;
+    const check = parseCheckSpec(raw.check, name);
     const postInstall = typeof raw.post_install === 'string' ? raw.post_install : undefined;
     if (!Array.isArray(raw.install) || raw.install.length === 0) {
         throw new Error('install must be a non-empty list of methods');
@@ -44,11 +140,29 @@ export function parseCliManifest(contents, opts) {
         }
         const key = keys[0];
         const value = e[key];
-        if (key === 'npm' || key === 'brew' || key === 'script') {
+        if (key === 'npm') {
+            if (typeof value !== 'string' || !value.trim()) {
+                throw new Error(`install[${i}].npm must be a non-empty string`);
+            }
+            const v = value.trim();
+            assertNpmPackage(v);
+            return { npm: v };
+        }
+        if (key === 'brew') {
+            if (typeof value !== 'string' || !value.trim()) {
+                throw new Error(`install[${i}].brew must be a non-empty string`);
+            }
+            const v = value.trim();
+            assertBrewFormula(v);
+            return { brew: v };
+        }
+        if (key === 'script') {
             if (typeof value !== 'string' || !value.trim()) {
-                throw new Error(`install[${i}].${key} must be a non-empty string`);
+                throw new Error(`install[${i}].script must be a non-empty string`);
             }
-            return { [key]: value.trim() };
+            const v = value.trim();
+            assertHttpsUrl(v);
+            return { script: v };
         }
         if (key === 'binary') {
             if (!value || typeof value !== 'object') {
@@ -63,10 +177,14 @@ export function parseCliManifest(contents, opts) {
                 if (typeof s.url !== 'string' || !s.url.trim()) {
                     throw new Error(`install[${i}].binary.${platform}.url must be a non-empty string`);
                 }
-                binary[platform] = {
-                    url: s.url.trim(),
-                    extract: typeof s.extract === 'string' ? s.extract : undefined,
-                };
+                const url = s.url.trim();
+                assertHttpsUrl(url);
+                let extract;
+                if (typeof s.extract === 'string' && s.extract.length > 0) {
+                    assertSafePathSegment(s.extract);
+                    extract = s.extract;
+                }
+                binary[platform] = { url, extract };
             }
             return { binary };
         }
@@ -125,25 +243,34 @@ export function resolveCliManifest(name, cwd) {
 }
 // ─── Host detection ──────────────────────────────────────────────────────────
 /**
- * Return true if a command resolves on the current PATH. Uses `which` on
- * POSIX hosts; results are cached for the lifetime of the process.
+ * Return true if a command resolves on the current PATH. Uses POSIX `command -v`
+ * via spawn argv (no shell); results are cached for the lifetime of the process.
  */
 const cmdExistsCache = new Map();
 export function hasCommand(cmd) {
     if (cmdExistsCache.has(cmd))
         return cmdExistsCache.get(cmd);
-    const result = spawnSync('command', ['-v', cmd], { shell: true, stdio: 'ignore' });
+    // `command` is a shell builtin on most POSIX shells; invoking `sh -c 'command -v X'`
+    // with X as an *argument* (not interpolated) is the safe path. `cmd` may be passed
+    // by callers that haven't validated it, so we route via argv to neutralize metas.
+    const result = spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', '_', cmd], {
+        stdio: 'ignore',
+    });
     const ok = result.status === 0;
     cmdExistsCache.set(cmd, ok);
     return ok;
 }
-/** Run the manifest's `check` command. Returns true when it exits 0. */
+/**
+ * Run the manifest's check. Dispatches on CheckSpec.kind — never invokes a
+ * shell, never interpolates strings into a command line.
+ */
 export function isCliInstalled(manifest) {
-    const result = spawnSync(manifest.check, {
-        shell: true,
-        stdio: 'ignore',
-        timeout: 10_000,
-    });
+    const c = manifest.check;
+    if (c.kind === 'which') {
+        cmdExistsCache.delete(c.cmd);
+        return hasCommand(c.cmd);
+    }
+    const result = spawnSync(c.cmd, c.args, { stdio: 'ignore', timeout: 10_000 });
     return result.status === 0;
 }
 // ─── Method selection ────────────────────────────────────────────────────────
@@ -167,6 +294,10 @@ export function selectInstallMethod(manifest) {
     }
     return null;
 }
+/** Render a CheckSpec back to a human-readable command string (display only). */
+export function describeCheck(check) {
+    return check.kind === 'which' ? check.cmd : `${check.cmd} ${check.args.join(' ')}`.trim();
+}
 /** Short description of a method for display. */
 export function describeMethod(method) {
     if ('npm' in method)
@@ -179,6 +310,122 @@ export function describeMethod(method) {
     const spec = method.binary[key];
     return spec ? `download ${spec.url}` : 'binary download';
 }
+/**
+ * Display-only rendering of how a method would be run, for `--dry-run` and
+ * status output. Not used by installCli — execution goes through runInstallMethod
+ * which dispatches to spawnSync with argv arrays.
+ */
+export function buildInstallCommand(method) {
+    if ('npm' in method)
+        return `npm install -g ${method.npm}`;
+    if ('brew' in method)
+        return `brew install ${method.brew}`;
+    if ('script' in method) {
+        return hasCommand('curl')
+            ? `curl -fsSL ${method.script} | sh`
+            : `wget -qO- ${method.script} | sh`;
+    }
+    const key = `${process.platform}-${process.arch}`;
+    const spec = method.binary[key];
+    if (!spec)
+        return 'binary download';
+    return spec.extract
+        ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C /usr/local/bin ${spec.extract}`
+        : `curl -fsSL ${spec.url} -o /usr/local/bin/agents-cli-downloaded`;
+}
+/**
+ * Execute an install method via spawnSync with argv arrays. Each branch
+ * re-validates the relevant field — defense in depth, since callers may
+ * construct InstallMethod values without going through parseCliManifest
+ * (tests, future programmatic use).
+ *
+ * For `script`, the download is staged to a temp file and then exec'd as
+ * `sh <file>` so we never need a shell pipe (`curl | sh`).
+ */
+function runInstallMethod(method) {
+    if ('npm' in method) {
+        assertNpmPackage(method.npm);
+        const r = spawnSync('npm', ['install', '-g', method.npm], { stdio: 'inherit' });
+        if (r.status !== 0) {
+            throw new Error(`npm install -g ${method.npm} exited with status ${r.status ?? 'unknown'}`);
+        }
+        return;
+    }
+    if ('brew' in method) {
+        assertBrewFormula(method.brew);
+        const r = spawnSync('brew', ['install', method.brew], { stdio: 'inherit' });
+        if (r.status !== 0) {
+            throw new Error(`brew install ${method.brew} exited with status ${r.status ?? 'unknown'}`);
+        }
+        return;
+    }
+    if ('script' in method) {
+        assertHttpsUrl(method.script);
+        const tmp = path.join(os.tmpdir(), `agents-cli-install-${process.pid}-${Date.now()}.sh`);
+        try {
+            let dl;
+            if (hasCommand('curl')) {
+                dl = spawnSync('curl', ['-fsSL', method.script, '-o', tmp], { stdio: 'inherit' });
+            }
+            else if (hasCommand('wget')) {
+                dl = spawnSync('wget', ['-q', '-O', tmp, method.script], { stdio: 'inherit' });
+            }
+            else {
+                throw new Error('neither curl nor wget is available on PATH');
+            }
+            if (dl.status !== 0) {
+                throw new Error(`download of install script failed (status ${dl.status ?? 'unknown'})`);
+            }
+            const r = spawnSync('sh', [tmp], { stdio: 'inherit' });
+            if (r.status !== 0) {
+                throw new Error(`install script exited with status ${r.status ?? 'unknown'}`);
+            }
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* best effort */ }
+        }
+        return;
+    }
+    if ('binary' in method) {
+        const key = `${process.platform}-${process.arch}`;
+        const spec = method.binary[key];
+        if (!spec)
+            throw new Error(`no binary declared for ${key}`);
+        assertHttpsUrl(spec.url);
+        if (spec.extract) {
+            assertSafePathSegment(spec.extract);
+            const tmp = path.join(os.tmpdir(), `agents-cli-bin-${process.pid}-${Date.now()}.tgz`);
+            try {
+                const dl = spawnSync('curl', ['-fsSL', spec.url, '-o', tmp], { stdio: 'inherit' });
+                if (dl.status !== 0) {
+                    throw new Error(`binary download failed (status ${dl.status ?? 'unknown'})`);
+                }
+                const x = spawnSync('tar', ['-xzf', tmp, '-C', '/usr/local/bin', spec.extract], {
+                    stdio: 'inherit',
+                });
+                if (x.status !== 0) {
+                    throw new Error(`tar extract failed (status ${x.status ?? 'unknown'})`);
+                }
+            }
+            finally {
+                try {
+                    fs.unlinkSync(tmp);
+                }
+                catch { /* best effort */ }
+            }
+        }
+        else {
+            const r = spawnSync('curl', ['-fsSL', spec.url, '-o', '/usr/local/bin/agents-cli-downloaded'], { stdio: 'inherit' });
+            if (r.status !== 0) {
+                throw new Error(`binary download failed (status ${r.status ?? 'unknown'})`);
+            }
+        }
+        return;
+    }
+}
 /**
  * Install a single CLI by running its first compatible method. Streams the
  * underlying command's output to the parent terminal so users see brew/npm
@@ -197,9 +444,8 @@ export function installCli(manifest, opts = {}) {
     if (opts.dryRun) {
         return { manifest, method, installed: false, output: `[dry-run] would run: ${describeMethod(method)}` };
     }
-    const cmd = buildInstallCommand(method);
     try {
-        execSync(cmd, { stdio: 'inherit' });
+        runInstallMethod(method);
     }
     catch (err) {
         return {
@@ -216,30 +462,6 @@ export function installCli(manifest, opts = {}) {
     const installed = isCliInstalled(manifest);
     return { manifest, method, installed };
 }
-/**
- * Map a declarative method to a shell command. Centralized so tests and dry-run
- * surface the exact string that would execute.
- */
-export function buildInstallCommand(method) {
-    if ('npm' in method)
-        return `npm install -g ${method.npm}`;
-    if ('brew' in method)
-        return `brew install ${method.brew}`;
-    if ('script' in method) {
-        // Prefer curl when both are present; fall back to wget.
-        return hasCommand('curl')
-            ? `curl -fsSL ${method.script} | sh`
-            : `wget -qO- ${method.script} | sh`;
-    }
-    const key = `${process.platform}-${process.arch}`;
-    const spec = method.binary[key];
-    // The downloader is intentionally minimal — binary install is mostly used
-    // for pre-built tarballs whose extract path varies per project. We expect
-    // the manifest author to document any post-download steps in post_install.
-    return spec.extract
-        ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C /usr/local/bin ${spec.extract}`
-        : `curl -fsSL ${spec.url} -o /usr/local/bin/agents-cli-downloaded`;
-}
 /** Convenience: list all manifests + their installed-on-host status. */
 export function listCliStatus(cwd) {
     const { manifests, errors } = listCliManifests(cwd);

package/dist/lib/cloud/factory.d.ts

@@ -8,7 +8,7 @@ import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOpt
 /**
  * Factory/Droid cloud provider — stub for Phase 2.
  *
- * Integration path: `droid daemon` running on a remote machine (mac-mini, cloud VM, k8s pod).
+ * Integration path: `droid daemon` running on a remote machine (workstation, cloud VM, k8s pod).
  * Dispatch via HTTP to the daemon, stream output, cancel via HTTP DELETE.
  *
  * Not yet implemented because:

package/dist/lib/cloud/factory.js

@@ -7,7 +7,7 @@
 /**
  * Factory/Droid cloud provider — stub for Phase 2.
  *
- * Integration path: `droid daemon` running on a remote machine (mac-mini, cloud VM, k8s pod).
+ * Integration path: `droid daemon` running on a remote machine (workstation, cloud VM, k8s pod).
  * Dispatch via HTTP to the daemon, stream output, cancel via HTTP DELETE.
  *
  * Not yet implemented because:

package/dist/lib/events.d.ts

@@ -32,7 +32,8 @@ export interface EventPayload {
     args?: string[];
     input?: string;
     output?: string;
-    prompt?: string;
+    prompt_length?: number;
+    prompt_sha256?: string;
     durationMs?: number;
     startupMs?: number;
     exitCode?: number;
@@ -42,6 +43,19 @@ export interface EventPayload {
     [key: string]: unknown;
 }
 export type EventRecord = EventMeta & EventPayload;
+/**
+ * Replace a prompt string with length + short SHA so we can correlate runs
+ * without persisting the raw text. Returns the fields to spread into a payload.
+ */
+export declare function redactPrompt(prompt: string | null | undefined): {
+    prompt_length?: number;
+    prompt_sha256?: string;
+};
+/**
+ * Mask argv entries that look like tokens or secret paths. Preserves structure
+ * for debugging but drops the sensitive substring.
+ */
+export declare function redactArgs(args: string[] | undefined): string[] | undefined;
 /**
  * Truncate a string to maxLength, adding ellipsis if truncated.
  * Returns undefined for null/undefined input.
@@ -124,7 +138,7 @@ export declare function emitError(err: Error | string, payload?: EventPayload):
  * Remove log files older than the retention period.
  * Called lazily on emit or explicitly via CLI.
  *
- * @param retentionDays - Number of days to keep (default 30)
+ * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
  * @returns Number of files removed
  */
 export declare function rotate(retentionDays?: number): number;

package/dist/lib/events.js

@@ -14,11 +14,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { createHash } from 'node:crypto';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Logs live under the cache bucket — they're regenerable telemetry.
 const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
 /** Default retention period in days. */
-const DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_RETENTION_DAYS = 7;
 /** Default max length for truncated strings. */
 const DEFAULT_TRUNCATE_LENGTH = 500;
 /** Environment variable to disable event logging. */
@@ -68,6 +69,36 @@ function ensureLogsDir() {
         }
     }
 }
+// ─── Redaction ────────────────────────────────────────────────────────────────
+/**
+ * Replace a prompt string with length + short SHA so we can correlate runs
+ * without persisting the raw text. Returns the fields to spread into a payload.
+ */
+export function redactPrompt(prompt) {
+    if (prompt == null)
+        return {};
+    return {
+        prompt_length: prompt.length,
+        prompt_sha256: createHash('sha256').update(prompt).digest('hex').slice(0, 16),
+    };
+}
+const TOKEN_LIKE = /(sk_(?:live|test)_|pk_(?:live|test)_|ghp_|gho_|ghu_|ghs_|xox[bpars]-|AKIA|ASIA|AIza|Bearer\s+|eyJ[A-Za-z0-9_-]+\.)/i;
+const SECRET_PATH = /\/(secrets|credentials|\.env|user\.yaml)\b/i;
+/**
+ * Mask argv entries that look like tokens or secret paths. Preserves structure
+ * for debugging but drops the sensitive substring.
+ */
+export function redactArgs(args) {
+    if (!args)
+        return undefined;
+    return args.map(a => {
+        if (typeof a !== 'string')
+            return a;
+        if (TOKEN_LIKE.test(a) || SECRET_PATH.test(a))
+            return '[REDACTED]';
+        return a;
+    });
+}
 // ─── Truncation ───────────────────────────────────────────────────────────────
 /**
  * Truncate a string to maxLength, adding ellipsis if truncated.
@@ -324,7 +355,7 @@ export function emitError(err, payload = {}) {
  * Remove log files older than the retention period.
  * Called lazily on emit or explicitly via CLI.
  *
- * @param retentionDays - Number of days to keep (default 30)
+ * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
  * @returns Number of files removed
  */
 export function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {

package/dist/lib/exec.d.ts

@@ -1,6 +1,28 @@
-import type { AgentId } from './types.js';
-/** Agent execution modes controlling tool access and autonomy level. */
-export type ExecMode = 'plan' | 'edit' | 'full' | 'auto';
+import type { AgentId, Mode } from './types.js';
+/**
+ * Agent execution modes. Canonical name `skip` (dangerously skip permissions);
+ * `full` is accepted as a permanent silent alias via normalizeMode().
+ */
+export type ExecMode = Mode;
+/**
+ * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
+ *
+ * Accepts the historical `full` spelling and rewrites it to `skip`. Throws on
+ * anything outside the four canonical values so bad input fails loud at the
+ * boundary rather than silently picking a wrong code path.
+ */
+export declare function normalizeMode(input: string | null | undefined): Mode;
+/**
+ * Resolve a requested mode against an agent's capability table.
+ *
+ * - `auto` on an agent without auto support silently degrades to `edit`
+ *   (every agent supports edit-like behavior as its default).
+ * - `skip` on an agent without skip support throws with a clear message
+ *   naming the agent's supported modes. No silent fallback — the user
+ *   explicitly asked to bypass permissions; pretending we did is unsafe.
+ * - `plan` on an agent without plan support throws the same way.
+ */
+export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
@@ -32,22 +54,28 @@ export declare function parseExecEnv(entries: string[]): Record<string, string>
  * into unrelated invocations.
  */
 export declare function buildExecEnv(options: ExecOptions): NodeJS.ProcessEnv;
-/** Describes how to translate ExecOptions into CLI arguments for a specific agent. */
+/**
+ * Describes how to translate ExecOptions into CLI arguments for a specific agent.
+ *
+ * `modeFlags` only declares modes this agent natively supports. Keys must agree
+ * with AGENTS[agent].capabilities.modes — resolveMode() routes a request to a
+ * supported mode (or throws), then buildExecCommand looks up the flags here.
+ */
 export interface AgentCommandTemplate {
     base: string[];
     promptFlag: 'positional' | string;
-    modeFlags: {
-        plan: string[];
-        edit: string[];
-        full: string[];
-        auto?: string[];
-    };
+    modeFlags: Partial<Record<Mode, string[]>>;
     jsonFlags?: string[];
     modelFlag?: string;
     printFlags?: string[];
     verboseFlag?: string;
 }
-/** CLI command templates for every supported agent. */
+/**
+ * CLI command templates for every supported agent.
+ *
+ * Each agent's `modeFlags` keys MUST match the modes listed in
+ * AGENTS[agent].capabilities.modes. A test in exec.test.ts asserts this.
+ */
 export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];