@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/lib/refresh.js

@@ -29,7 +29,7 @@ import { isPromptCancelled } from '../commands/utils.js';
  * hook reads from a fixed path so it survives version upgrades. If the root
  * file doesn't exist yet but an agent-scoped one does, hoist the first one found.
  */
-function migratePromptcutsToRoot(agentsDir) {
+function migratePromptcutsToRoot(agentsDir, quiet = false) {
     const rootPath = path.join(agentsDir, 'promptcuts.yaml');
     if (fs.existsSync(rootPath))
         return;
@@ -39,7 +39,8 @@ function migratePromptcutsToRoot(agentsDir) {
         if (fs.existsSync(legacyPath)) {
             try {
                 fs.renameSync(legacyPath, rootPath);
-                console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
+                if (!quiet)
+                    console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
                 return;
             }
             catch {
@@ -56,16 +57,19 @@ function migratePromptcutsToRoot(agentsDir) {
  * Idempotent — safe to run repeatedly. No network operations.
  */
 export async function refresh(options = {}) {
-    const { agentFilter, skipPrompts = false, skipClis = false } = options;
+    const { agentFilter, skipPrompts = false, skipClis = false, quiet = false } = options;
     const agentsDir = getUserAgentsDir();
-    migratePromptcutsToRoot(agentsDir);
+    // Gate every human progress line so --json / fleet fan-out can parse stdout.
+    const log = (...args) => { if (!quiet)
+        console.log(...args); };
+    migratePromptcutsToRoot(agentsDir, quiet);
     const manifest = readManifest(agentsDir);
     if (!manifest) {
-        console.log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
+        log(chalk.gray(`No ${MANIFEST_FILENAME} found`));
     }
     // 1. Install/upgrade CLI versions from agents.yaml
     if (!skipClis && manifest?.agents) {
-        console.log(chalk.bold('\nCLI Versions:\n'));
+        log(chalk.bold('\nCLI Versions:\n'));
         const cliAgents = Object.keys(manifest.agents);
         for (const agentId of cliAgents) {
             if (agentFilter && agentId !== agentFilter)
@@ -94,7 +98,7 @@ export async function refresh(options = {}) {
     }
     // 2. Register MCP servers
     if (manifest?.mcp && Object.keys(manifest.mcp).length > 0) {
-        console.log(chalk.bold('\nMCP Servers:\n'));
+        log(chalk.bold('\nMCP Servers:\n'));
         for (const [name, config] of Object.entries(manifest.mcp)) {
             if (!config.command || config.transport === 'http')
                 continue;
@@ -109,7 +113,7 @@ export async function refresh(options = {}) {
                     const label = result.version
                         ? `${agentLabel(result.agentId)}@${result.version}`
                         : agentLabel(result.agentId);
-                    console.log(`  ${chalk.green('+')} ${name} -> ${label}`);
+                    log(`  ${chalk.green('+')} ${name} -> ${label}`);
                 }
             }
         }
@@ -147,13 +151,13 @@ export async function refresh(options = {}) {
                 forceFullSync = true;
             }
             else if (!hasAnySynced) {
-                console.log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
+                log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
                 const userSelection = await promptResourceSelection(agentId);
                 if (userSelection)
                     selection = userSelection;
             }
             else if (hasNewResources(newResources, agentId, defaultVer)) {
-                console.log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
+                log(chalk.cyan(`\n${agentLabel(agentId)}@${defaultVer}:`));
                 const userSelection = await promptNewResourceSelection(agentId, newResources, defaultVer);
                 if (userSelection)
                     selection = userSelection;
@@ -184,13 +188,13 @@ export async function refresh(options = {}) {
                     const verNote = versionsToSync.length > 1
                         ? chalk.gray(` (${versionsToSync.length} versions)`)
                         : '';
-                    console.log(chalk.green(`  Synced: ${[...kinds].join(', ')}`) + verNote);
+                    log(chalk.green(`  Synced: ${[...kinds].join(', ')}`) + verNote);
                 }
             }
         }
         catch (err) {
             if (isPromptCancelled(err)) {
-                console.log(chalk.gray('Skipped resource selection'));
+                log(chalk.gray('Skipped resource selection'));
             }
             else {
                 throw err;
@@ -215,24 +219,24 @@ export async function refresh(options = {}) {
                 const result = registerHooksToSettings(agentId, home, hookManifest);
                 hookRegistered += result.registered.length;
                 for (const error of result.errors) {
-                    console.log(chalk.yellow(`  Hook warning: ${error}`));
+                    log(chalk.yellow(`  Hook warning: ${error}`));
                 }
             }
         }
         if (hookRegistered > 0) {
-            console.log(chalk.green(`\nRegistered ${hookRegistered} hook lifecycle event(s)`));
+            log(chalk.green(`\nRegistered ${hookRegistered} hook lifecycle event(s)`));
         }
     }
     // 5. Auto-add shims to PATH
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {
-            console.log(chalk.green(`\nAdded shims to ${pathResult.location}`));
-            console.log(chalk.gray(pathResult.reloadHint));
+            log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+            log(chalk.gray(pathResult.reloadHint));
         }
         else if (!pathResult.success) {
-            console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));
-            console.log(chalk.gray(getPathSetupInstructions()));
+            log(chalk.yellow('\nCould not auto-add shims to PATH:'));
+            log(chalk.gray(getPathSetupInstructions()));
         }
     }
     // 6. Prompt for missing default versions
@@ -273,63 +277,63 @@ export async function refresh(options = {}) {
             setGlobalDefault(agentId, version);
             const symlinkResult = await switchConfigSymlink(agentId, version);
             if (!symlinkResult.success) {
-                console.log(chalk.yellow(`Warning: ${symlinkResult.error}`));
+                log(chalk.yellow(`Warning: ${symlinkResult.error}`));
             }
             else if (symlinkResult.backupPath) {
-                console.log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
+                log(chalk.gray(`Backed up existing config to: ${symlinkResult.backupPath}`));
             }
             switchHomeFileSymlinks(agentId, version);
-            console.log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
+            log(chalk.green(`Set ${agentLabel(agent.id)}@${version} as default`));
         }
     }
     // 7. Install declared host-CLIs
     try {
         const { statuses, errors } = listCliStatus(process.cwd());
         for (const err of errors) {
-            console.log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
+            log(chalk.yellow(`  CLI manifest parse error: ${err.file}: ${err.reason}`));
         }
         const missing = statuses.filter((s) => !s.installed);
         if (missing.length > 0) {
-            console.log(chalk.bold('\nDeclared CLIs missing from this host:'));
+            log(chalk.bold('\nDeclared CLIs missing from this host:'));
             for (const s of missing) {
                 const method = selectInstallMethod(s.manifest);
                 const action = method ? describeMethod(method) : chalk.red('no compatible install method');
-                console.log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
+                log(`  ${chalk.cyan(s.manifest.name.padEnd(20))} ${chalk.gray(action)}`);
             }
-            console.log('');
+            log('');
             if (!skipPrompts) {
                 const proceed = await confirm({ message: `Install ${missing.length} missing CLI(s) now?`, default: true });
                 if (proceed) {
                     for (const s of missing) {
-                        console.log(chalk.bold(`\n→ ${s.manifest.name}`));
+                        log(chalk.bold(`\n→ ${s.manifest.name}`));
                         const result = installCli(s.manifest);
                         if (result.error) {
-                            console.log(chalk.red(`  ${result.error}`));
+                            log(chalk.red(`  ${result.error}`));
                             continue;
                         }
                         if (result.installed) {
-                            console.log(chalk.green(`  installed`));
+                            log(chalk.green(`  installed`));
                             if (s.manifest.postInstall) {
-                                console.log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
+                                log(chalk.gray(s.manifest.postInstall.trim().split('\n').map((l) => '  ' + l).join('\n')));
                             }
                         }
                         else {
-                            console.log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
+                            log(chalk.yellow(`  install ran but \`${describeCheck(s.manifest.check)}\` still fails`));
                         }
                     }
                 }
                 else {
-                    console.log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
+                    log(chalk.gray(`Skipped. Run 'agents cli install' later.`));
                 }
             }
             else {
-                console.log(chalk.gray(`Run 'agents cli install' to install them.`));
+                log(chalk.gray(`Run 'agents cli install' to install them.`));
             }
         }
     }
     catch (err) {
         if (!isPromptCancelled(err)) {
-            console.log(chalk.yellow(`CLI install skipped: ${err.message}`));
+            log(chalk.yellow(`CLI install skipped: ${err.message}`));
         }
     }
 }

package/dist/lib/resource-inventory.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Resource inventory — the single chokepoint for "what does this agent@version
+ * have" (RUSH-2238, parent RUSH-2236; spec: openspec/specs/resource-inventory).
+ *
+ * One API answers four orthogonal questions per (agent, version, kind):
+ *
+ *   capable   — the agent+version feature flags allow the kind at all
+ *   declared  — resources the DotAgents layers (project/user/system/extra)
+ *               declare for sync
+ *   onDisk    — resources actually installed in the version home filesystem
+ *               (the installed-resource truth — NOT agents.yaml tracking data)
+ *   wired     — resources the harness native config references so they fire
+ *   unmanaged — onDisk − declared (orphans no layer declares anymore)
+ *
+ * Callers (inspect, doctor, view, sync) MUST come here rather than
+ * re-implementing path joins or config parsing per command. Wiring parsing
+ * currently covers the settings.json family (claude, droid,
+ * muse), Grok hooks.json, and Kimi config.toml via checkVersionHookWiring.
+ */
+import type { AgentId } from './types.js';
+import { type HookWiringReport } from './hooks.js';
+/** Resource kinds the inventory can report. Only 'hooks' is implemented so far
+ *  (RUSH-2238); the remaining kinds land with their follow-up tickets. */
+export type InventoryKind = 'hooks' | 'skills' | 'commands' | 'plugins' | 'mcp';
+/** A reference to one resource in one state (declared / onDisk / wired). */
+export interface ResourceRef {
+    /** Stable install name (script basename without extension for hooks). */
+    name: string;
+    /** Declared/onDisk: absolute file path. Wired: the command string the native
+     *  config references. */
+    path: string;
+    /** Origin: a layer name for declared ('project' | 'user' | 'system' | extra
+     *  repo alias), 'user'/'project' scope or 'version-home' for onDisk,
+     *  'native-config' for wired. */
+    source: string;
+    /** Optional context — e.g. the lifecycle events a wired hook fires on. */
+    detail?: string;
+}
+export interface ResourceInventory {
+    agent: AgentId;
+    version: string;
+    kind: InventoryKind;
+    /** Agent+version feature flags allow this kind (version-aware gate). */
+    capable: boolean;
+    /** Declared in the DotAgents layers. */
+    declared: ResourceRef[];
+    /** Installed on disk in the version home. */
+    onDisk: ResourceRef[];
+    /** Referenced by the harness native config (empty when wiringSupported is
+     *  false — the format parser for that harness is not implemented yet). */
+    wired: ResourceRef[];
+    /** onDisk − declared: installed orphans no layer declares. */
+    unmanaged: ResourceRef[];
+    /** Whether this harness's native wiring was read successfully. When false,
+     *  `wired: []` means "unknown" (unsupported family OR unparseable config),
+     *  NOT "nothing wired". Format-supported but corrupt configs set this false. */
+    wiringSupported: boolean;
+    /** Native-format diagnostic retained for doctor; derived in this same pass. */
+    wiring?: HookWiringReport;
+}
+/**
+ * The single inventory API. Harness-scoped (claude/codex/grok/kimi/droid) —
+ * never a model or profile. Throws for kinds without an implementation rather
+ * than returning a half-empty report that looks like truth.
+ */
+export declare function getResourceInventory(agent: AgentId, version: string, kind: InventoryKind, opts?: {
+    cwd?: string;
+}): ResourceInventory;
+/**
+ * On-disk hook listing for an explicit home (version home or effective home)
+ * plus the project overlay — the one listing `getAgentResources` routes
+ * through, so inspect/doctor/view share a single hooks source. Paths resolve
+ * through the absolute-hooksDir-safe join (RUSH-2237), so grok/kimi version
+ * homes list their real hooks.
+ */
+export declare function listOnDiskHooks(agent: AgentId, opts?: {
+    home?: string;
+    cwd?: string;
+}): ResourceRef[];

package/dist/lib/resource-inventory.js

@@ -0,0 +1,122 @@
+/**
+ * Resource inventory — the single chokepoint for "what does this agent@version
+ * have" (RUSH-2238, parent RUSH-2236; spec: openspec/specs/resource-inventory).
+ *
+ * One API answers four orthogonal questions per (agent, version, kind):
+ *
+ *   capable   — the agent+version feature flags allow the kind at all
+ *   declared  — resources the DotAgents layers (project/user/system/extra)
+ *               declare for sync
+ *   onDisk    — resources actually installed in the version home filesystem
+ *               (the installed-resource truth — NOT agents.yaml tracking data)
+ *   wired     — resources the harness native config references so they fire
+ *   unmanaged — onDisk − declared (orphans no layer declares anymore)
+ *
+ * Callers (inspect, doctor, view, sync) MUST come here rather than
+ * re-implementing path joins or config parsing per command. Wiring parsing
+ * currently covers the settings.json family (claude, droid,
+ * muse), Grok hooks.json, and Kimi config.toml via checkVersionHookWiring.
+ */
+import { AGENTS } from './agents.js';
+import { supports } from './capabilities.js';
+import { listResources } from './resources.js';
+import { checkVersionHookWiring, listHooksInVersionHome, listInstalledHooksWithScope, } from './hooks.js';
+const IMPLEMENTED_KINDS = ['hooks'];
+/**
+ * The single inventory API. Harness-scoped (claude/codex/grok/kimi/droid) —
+ * never a model or profile. Throws for kinds without an implementation rather
+ * than returning a half-empty report that looks like truth.
+ */
+export function getResourceInventory(agent, version, kind, opts = {}) {
+    if (!IMPLEMENTED_KINDS.includes(kind)) {
+        // Fail loud at the boundary: the kind is part of the API shape but its
+        // inventory lands with a RUSH-2236 follow-up — a silent empty report would
+        // read as "nothing installed".
+        throw new Error(`getResourceInventory: kind '${kind}' is not implemented yet (implemented: ${IMPLEMENTED_KINDS.join(', ')}; tracked under RUSH-2236)`);
+    }
+    return hooksInventory(agent, version, opts.cwd);
+}
+/**
+ * On-disk hook listing for an explicit home (version home or effective home)
+ * plus the project overlay — the one listing `getAgentResources` routes
+ * through, so inspect/doctor/view share a single hooks source. Paths resolve
+ * through the absolute-hooksDir-safe join (RUSH-2237), so grok/kimi version
+ * homes list their real hooks.
+ */
+export function listOnDiskHooks(agent, opts = {}) {
+    return listInstalledHooksWithScope(agent, opts.cwd ?? process.cwd(), { home: opts.home }).map((h) => ({
+        name: h.name,
+        path: h.path,
+        source: h.scope,
+        detail: h.dataFile,
+    }));
+}
+function hooksInventory(agent, version, cwd) {
+    const capable = supports(agent, 'hooks', version).ok;
+    // Declared: the layered DotAgents repos are the declaration surface. Hook
+    // script names carry their extension here ('git-guard.sh'); normalize to the
+    // extension-less install name so declared/onDisk sets compare.
+    const declared = listResources('hooks', cwd).map((r) => ({
+        name: r.name.replace(/\.[^./]+$/, ''),
+        path: r.path,
+        source: r.source,
+    }));
+    // onDisk / wired need the version home; both are empty for an agent whose
+    // hooks capability is gated off (unknown agents included — AGENTS lookup
+    // would otherwise throw).
+    let onDisk = [];
+    let wired = [];
+    let wiringSupported = false;
+    let wiring;
+    if (capable && AGENTS[agent]?.supportsHooks) {
+        onDisk = listHooksInVersionHome(agent, version).map((e) => ({
+            name: e.name,
+            path: e.scriptPath,
+            source: 'version-home',
+            detail: e.dataFile,
+        }));
+        const report = checkVersionHookWiring(agent, version);
+        wiring = report;
+        // supported=true means the harness format is known; settingsUnparseable means
+        // we could not trust the file. Only report wired counts when the parse succeeded —
+        // otherwise inspect/doctor would render "wired 0" for corrupt configs (PR #2140 review).
+        wiringSupported = report.supported && !report.settingsUnparseable;
+        if (wiringSupported) {
+            // One ref per hook, events folded into detail — a hook wired under
+            // PreToolUse AND Stop is one inventory entry, not two.
+            const eventsByName = new Map();
+            const commandByName = new Map();
+            for (const issue of report.wired) {
+                let events = eventsByName.get(issue.name);
+                if (!events) {
+                    events = new Set();
+                    eventsByName.set(issue.name, events);
+                    commandByName.set(issue.name, issue.command);
+                }
+                events.add(issue.event);
+            }
+            wired = [...eventsByName.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([name, events]) => ({
+                name,
+                path: commandByName.get(name),
+                source: 'native-config',
+                detail: [...events].sort().join('/'),
+            }));
+        }
+    }
+    const declaredNames = new Set(declared.map((r) => r.name));
+    const unmanaged = onDisk.filter((r) => !declaredNames.has(r.name));
+    return {
+        agent,
+        version,
+        kind: 'hooks',
+        capable,
+        declared,
+        onDisk,
+        wired,
+        unmanaged,
+        wiringSupported,
+        wiring,
+    };
+}

package/dist/lib/resources/mcp.js

@@ -129,6 +129,9 @@ export function getMcpConfigPath(agent, versionHome) {
             return path.join(versionHome, '.omp', 'agent', '.mcp.json');
         case 'muse':
             return path.join(versionHome, '.config', 'muse', 'settings.json');
+        case 'warp':
+            // Oz reads user-scope MCP from ~/.warp/.mcp.json (Claude schema).
+            return path.join(versionHome, '.warp', '.mcp.json');
         default:
             return null;
     }

package/dist/lib/resources.js

@@ -7,7 +7,7 @@ import * as path from 'path';
 import { AGENTS, listInstalledMcpsWithScope } from './agents.js';
 import { listInstalledCommandsWithScope } from './commands.js';
 import { listInstalledSkillsWithScope } from './skills.js';
-import { listInstalledHooksWithScope } from './hooks.js';
+import { listOnDiskHooks } from './resource-inventory.js';
 import { listInstalledInstructionsWithScope } from './rules/rules.js';
 import { getEffectiveHome } from './versions.js';
 import { listMcpServerConfigs } from './mcp.js';
@@ -352,11 +352,14 @@ export function getAgentResources(agentId, options = {}) {
             });
         }
     }
-    // Hooks
+    // Hooks — routed through the resource-inventory chokepoint (RUSH-2238) so
+    // inspect/doctor/view share one listing and one (absolute-hooksDir-safe)
+    // path resolution.
     const hooks = [];
-    for (const hook of listInstalledHooksWithScope(agentId, cwd, { home })) {
-        if (shouldInclude(hook.scope)) {
-            hooks.push({ name: hook.name, path: hook.path, scope: hook.scope });
+    for (const ref of listOnDiskHooks(agentId, { cwd, home })) {
+        const hookScope = ref.source;
+        if (shouldInclude(hookScope)) {
+            hooks.push({ name: ref.name, path: ref.path, scope: hookScope });
         }
     }
     // Workflows

package/dist/lib/routine-process-cleanup.d.ts

@@ -0,0 +1,9 @@
+import type { RunMeta } from './routines.js';
+export interface RoutineProcessCleanupOptions {
+    runsDir?: string;
+    alive?: (pid: number) => boolean;
+    owns?: (meta: RunMeta) => boolean;
+    terminate?: (pid: number) => void;
+}
+/** Reap process groups whose durable run record is already terminal. */
+export declare function reapTerminalRoutineProcesses(opts?: RoutineProcessCleanupOptions): number[];

package/dist/lib/routine-process-cleanup.js

@@ -0,0 +1,73 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { isAlive, killTree } from './platform/index.js';
+import { getRunsDir } from './state.js';
+function processMatchesRun(meta) {
+    if (!meta.pid || !meta.spawnedAt)
+        return false;
+    try {
+        if (process.platform === 'win32') {
+            const startedAt = execFileSync('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-Process -Id ${meta.pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString("o")`,
+            ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
+            const processStart = Date.parse(startedAt);
+            return Number.isFinite(processStart) && Math.abs(processStart - meta.spawnedAt) < 30_000;
+        }
+        const elapsed = execFileSync('ps', ['-p', String(meta.pid), '-o', 'etime='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (!elapsed)
+            return false;
+        const fields = elapsed.replace(/-/g, ':').split(':').reverse();
+        const seconds = Number(fields[0] ?? 0)
+            + Number(fields[1] ?? 0) * 60
+            + Number(fields[2] ?? 0) * 3600
+            + Number(fields[3] ?? 0) * 86400;
+        return Math.abs((Date.now() - seconds * 1000) - meta.spawnedAt) < 30_000;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reap process groups whose durable run record is already terminal. */
+export function reapTerminalRoutineProcesses(opts = {}) {
+    const runsDir = opts.runsDir ?? getRunsDir();
+    const alive = opts.alive ?? isAlive;
+    const owns = opts.owns ?? processMatchesRun;
+    const terminate = opts.terminate ?? ((pid) => killTree(process.platform === 'win32' ? pid : -pid));
+    if (!fs.existsSync(runsDir))
+        return [];
+    const reaped = [];
+    for (const job of fs.readdirSync(runsDir, { withFileTypes: true })) {
+        if (!job.isDirectory())
+            continue;
+        const jobDir = path.join(runsDir, job.name);
+        for (const run of fs.readdirSync(jobDir, { withFileTypes: true })) {
+            if (!run.isDirectory())
+                continue;
+            try {
+                const meta = JSON.parse(fs.readFileSync(path.join(jobDir, run.name, 'meta.json'), 'utf-8'));
+                if (!['failed', 'timeout'].includes(meta.status) || !meta.pid || meta.hostTaskId || meta.cloudTaskId)
+                    continue;
+                const completedAt = Date.parse(meta.completedAt ?? '');
+                if (!Number.isFinite(completedAt) || Date.now() - completedAt < 5_000)
+                    continue;
+                if (!alive(meta.pid))
+                    continue;
+                if (!owns(meta))
+                    continue;
+                terminate(meta.pid);
+                reaped.push(meta.pid);
+            }
+            catch {
+                // Corrupt or concurrently-replaced records are left untouched.
+            }
+        }
+    }
+    return reaped;
+}

package/dist/lib/run-defaults.d.ts

@@ -21,6 +21,7 @@ export interface ResolvedRunDefaults extends RunDefaults {
     sources: {
         mode?: string;
         model?: string;
+        effort?: string;
     };
 }
 export interface RunDefaultEntry {
@@ -30,6 +31,7 @@ export interface RunDefaultEntry {
 type RunDefaultsInput = {
     mode?: unknown;
     model?: unknown;
+    effort?: unknown;
 };
 export declare function normalizeRunDefaultMode(input: string): Mode;
 export declare function parseRunDefaultSelector(input: string): ParsedRunDefaultSelector;

package/dist/lib/run-defaults.js

@@ -17,6 +17,7 @@ import { readMeta, updateMeta } from './state.js';
 import { getProjectRunConfigs } from './run-config.js';
 import chalk from 'chalk';
 const VERSION_RE = /^(?:\*|latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+const RUN_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'auto'];
 function isAgentId(value) {
     return value in AGENTS;
 }
@@ -42,6 +43,12 @@ function normalizeRunDefaults(defaults, selector) {
         }
         out.model = defaults.model.trim();
     }
+    if (defaults.effort !== undefined) {
+        if (typeof defaults.effort !== 'string' || !RUN_EFFORTS.includes(defaults.effort)) {
+            throw new Error('Invalid effort in run.defaults.' + selector + ': use one of: ' + RUN_EFFORTS.join(', ') + '.');
+        }
+        out.effort = defaults.effort;
+    }
     return out;
 }
 export function parseRunDefaultSelector(input) {
@@ -97,6 +104,10 @@ export function resolveRunDefaultsFromConfig(runConfig, agent, version) {
         resolved.model = wildcard.model;
         resolved.sources.model = wildcardSelector;
     }
+    if (wildcard?.effort) {
+        resolved.effort = wildcard.effort;
+        resolved.sources.effort = wildcardSelector;
+    }
     if (exactSelector && defaults[exactSelector]) {
         const exact = normalizeRunDefaults(defaults[exactSelector], exactSelector);
         if (exact.mode) {
@@ -107,6 +118,10 @@ export function resolveRunDefaultsFromConfig(runConfig, agent, version) {
             resolved.model = exact.model;
             resolved.sources.model = exactSelector;
         }
+        if (exact.effort) {
+            resolved.effort = exact.effort;
+            resolved.sources.effort = exactSelector;
+        }
     }
     return resolved;
 }
@@ -122,6 +137,10 @@ export function resolveRunDefaultsFromConfigs(runConfigs, agent, version) {
             resolved.model = next.model;
             resolved.sources.model = next.sources.model;
         }
+        if (next.effort) {
+            resolved.effort = next.effort;
+            resolved.sources.effort = next.sources.effort;
+        }
     }
     return resolved;
 }
@@ -135,6 +154,8 @@ export function formatRunDefaultEntry(entry) {
         parts.push(`mode ${chalk.white(entry.defaults.mode)}`);
     if (entry.defaults.model)
         parts.push(`model ${chalk.white(entry.defaults.model)}`);
+    if (entry.defaults.effort)
+        parts.push('effort ' + chalk.white(entry.defaults.effort));
     return `${chalk.cyan(entry.selector.padEnd(22))} ${parts.join('  ')}`;
 }
 export function listRunDefaults() {
@@ -149,8 +170,8 @@ export function listRunDefaults() {
 export function setRunDefault(selectorInput, defaultsInput) {
     const parsed = parseRunDefaultSelector(selectorInput);
     const defaults = normalizeRunDefaults(defaultsInput, parsed.selector);
-    if (!defaults.mode && !defaults.model) {
-        throw new Error('Set at least one default: --mode <mode> or --model <model>.');
+    if (!defaults.mode && !defaults.model && !defaults.effort) {
+        throw new Error('Set at least one default: --mode <mode>, --model <model>, or --effort <effort>.');
     }
     updateMeta((meta) => {
         const run = { ...(meta.run ?? {}) };