@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/state.d.ts

@@ -107,6 +107,10 @@ export declare function getRunsDir(): string;
 export declare function getVersionsDir(): string;
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export declare function getShimsDir(): string;
+/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
+export declare function getHookShimsDir(): string;
+/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
+export declare function getHookCacheDir(): string;
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export declare function getBinDir(): string;
 /** Path to config backups (~/.agents/.history/backups/). */
@@ -191,7 +195,16 @@ export declare function getEnabledExtraRepos(): Array<{
 export declare function ensureAgentsDir(): void;
 /** Return an empty Meta object used when no agents.yaml exists yet. */
 export declare function createDefaultMeta(): Meta;
-/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
+/**
+ * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
+ *
+ * Cache invariants:
+ * - Cache key is the mtime of the user agents.yaml.
+ * - `writeMetaUnlocked` clears the cache; in-process callers always see fresh state.
+ * - If the file is mutated by ANOTHER process while we hold a stale cache, the
+ *   mtime check below catches it on the next read (assuming the mtime advanced).
+ * - The cache stores the merged system+user meta; both files' mtimes contribute.
+ */
 export declare function readMeta(): Meta;
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export declare function writeMeta(meta: Meta): void;
@@ -212,7 +225,6 @@ export declare function recordVersionResources(_agent: AgentId, _version: string
  */
 export declare function ensureVersionResourcePatterns(agent: AgentId, version: string, updates: Partial<Record<Exclude<keyof VersionResources, 'rulesPreset'>, ResourcePattern[]>>): void;
 export declare function getVersionResources(agent: AgentId, version: string): VersionResources | null;
-export declare function clearVersionResources(agent: AgentId, version: string): void;
 /** Active rules preset for an agent@version. Defaults to "default" when unset. */
 export declare function getActiveRulesPreset(agent: AgentId, version: string): string;
 /** Persist the active rules preset for an agent@version. */

package/dist/lib/state.js

@@ -64,6 +64,8 @@ const BACKUPS_DIR = path.join(HISTORY_DIR, 'backups');
 const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
 // Cache bucket (regenerable).
 const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
+const HOOK_SHIMS_DIR = path.join(SHIMS_DIR, 'hooks');
+const HOOK_CACHE_DIR = path.join(CACHE_DIR, 'state', 'hooks');
 const BIN_DIR = path.join(CACHE_DIR, 'bin');
 const PACKAGES_DIR = path.join(CACHE_DIR, 'packages');
 // Plugins are user-authored resources, alongside skills/, commands/, hooks/.
@@ -74,7 +76,7 @@ const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
 const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
 const LOGS_DIR = path.join(CACHE_DIR, 'logs');
 const RUNTIME_STATE_DIR = path.join(CACHE_DIR, 'state');
-const SWARMIFY_DIR = path.join(CACHE_DIR, 'companion');
+const COMPANION_CACHE_DIR = path.join(CACHE_DIR, 'companion');
 const BROWSER_RUNTIME_DIR = path.join(CACHE_DIR, 'browser');
 const HELPERS_DIR = path.join(CACHE_DIR, 'helpers');
 const DAEMON_DIR = path.join(HELPERS_DIR, 'daemon');
@@ -265,6 +267,10 @@ export function getRunsDir() { return RUNS_DIR; }
 export function getVersionsDir() { return VERSIONS_DIR; }
 /** Path to version-switching shim scripts (~/.agents/.cache/shims/). */
 export function getShimsDir() { return SHIMS_DIR; }
+/** Path to generated per-hook caching/timing shims (~/.agents/.cache/shims/hooks/). */
+export function getHookShimsDir() { return HOOK_SHIMS_DIR; }
+/** Path to per-hook stdout cache files (~/.agents/.cache/state/hooks/). */
+export function getHookCacheDir() { return HOOK_CACHE_DIR; }
 /** Path to per-agent installed CLI binaries (~/.agents/.cache/bin/). */
 export function getBinDir() { return BIN_DIR; }
 /** Path to config backups (~/.agents/.history/backups/). */
@@ -294,7 +300,7 @@ export function getLogsDir() { return LOGS_DIR; }
 /** Path to per-process runtime state (~/.agents/.cache/state/). */
 export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */
-export function getCompanionDir() { return SWARMIFY_DIR; }
+export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
@@ -413,6 +419,24 @@ export function createDefaultMeta() {
 }
 let metaCache = null;
 let metaLockDepth = 0;
+/** Return mtimeMs for a file path, or 0 if the file is absent or unreadable. */
+function safeMtimeMs(filePath) {
+    try {
+        return fs.statSync(filePath).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Compute the combined cache stamp for the user + system agents.yaml files. */
+function currentMetaStamp() {
+    return safeMtimeMs(META_FILE) + safeMtimeMs(SYSTEM_META_FILE) * 1e-3;
+}
+/** Memoize a parsed Meta against the current file mtimes. */
+function rememberMeta(meta) {
+    metaCache = { mtime: currentMetaStamp(), meta };
+    return meta;
+}
 function withMetaLock(fn) {
     ensureAgentsDir();
     if (metaLockDepth > 0) {
@@ -483,9 +507,29 @@ function migrateSystemMetaToUser() {
         // Best-effort; proceed with fresh state if it fails.
     }
 }
-/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
+/**
+ * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
+ *
+ * Cache invariants:
+ * - Cache key is the mtime of the user agents.yaml.
+ * - `writeMetaUnlocked` clears the cache; in-process callers always see fresh state.
+ * - If the file is mutated by ANOTHER process while we hold a stale cache, the
+ *   mtime check below catches it on the next read (assuming the mtime advanced).
+ * - The cache stores the merged system+user meta; both files' mtimes contribute.
+ */
 export function readMeta() {
     ensureAgentsDir();
+    // Fast path: serve from cache when both source files are byte-identical to
+    // what we last parsed. Reduces N readMeta calls per CLI invocation to ~2 stat
+    // syscalls plus an in-memory object spread.
+    if (metaCache) {
+        const userMtime = safeMtimeMs(META_FILE);
+        const systemMtime = safeMtimeMs(SYSTEM_META_FILE);
+        const stamp = userMtime + systemMtime * 1e-3;
+        if (stamp === metaCache.mtime) {
+            return metaCache.meta;
+        }
+    }
     // NOTE: agents.yaml migration from ~/.agents-system/ to ~/.agents/ is handled
     // exclusively by runMigration() in migrate.ts, called from postinstall and
     // from a one-shot bootstrap step in src/index.ts. Calling it here would
@@ -515,7 +559,7 @@ export function readMeta() {
                 fs.unlinkSync(oldMetaFile);
             }
             catch { /* non-critical */ }
-            return meta;
+            return rememberMeta(meta);
         }
         catch {
             /* meta.yaml migration failed */
@@ -557,15 +601,15 @@ export function readMeta() {
         }
         if (applyRegistrySeeds(meta)) {
             writeMeta(meta);
-            return meta;
+            return rememberMeta(meta);
         }
-        return meta;
+        return rememberMeta(meta);
     }
     const meta = createDefaultMeta();
     if (applyRegistrySeeds(meta)) {
         writeMeta(meta);
     }
-    return meta;
+    return rememberMeta(meta);
 }
 /** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export function writeMeta(meta) {
@@ -626,19 +670,6 @@ export function getVersionResources(agent, version) {
     const meta = readMeta();
     return meta.versions?.[agent]?.[version] || null;
 }
-export function clearVersionResources(agent, version) {
-    const meta = readMeta();
-    if (meta.versions?.[agent]?.[version]) {
-        delete meta.versions[agent][version];
-        if (Object.keys(meta.versions[agent]).length === 0) {
-            delete meta.versions[agent];
-        }
-        if (Object.keys(meta.versions).length === 0) {
-            delete meta.versions;
-        }
-        writeMeta(meta);
-    }
-}
 /** Active rules preset for an agent@version. Defaults to "default" when unset. */
 export function getActiveRulesPreset(agent, version) {
     const meta = readMeta();

package/dist/lib/teams/agents.d.ts

@@ -36,8 +36,8 @@ export declare function captureProcessStartTime(pid: number): string | null;
  * model_reasoning_effort override). Mode (plan/edit/full) is a separate knob.
  */
 export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
-declare const VALID_MODES: readonly ["plan", "edit", "full", "auto"];
-type Mode = typeof VALID_MODES[number];
+export declare const VALID_MODES: readonly ["plan", "edit", "auto", "skip", "full"];
+type Mode = 'plan' | 'edit' | 'auto' | 'skip';
 /** Resolve a mode string to a validated Mode, falling back to the given default. */
 export declare function resolveMode(requestedMode: string | null | undefined, defaultMode?: Mode): Mode;
 /** Ensure Gemini's settings.json has experimental.plan enabled for headless plan mode. */
@@ -82,6 +82,7 @@ export declare class AgentProcess {
     after: string[];
     effort: EffortLevel | null;
     model: string | null;
+    profileName: string | null;
     envOverrides: Record<string, string> | null;
     taskType: TaskType | null;
     cloudRepo: string | null;
@@ -91,7 +92,7 @@ export declare class AgentProcess {
     private eventsCache;
     private lastReadPos;
     private baseDir;
-    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null);
+    constructor(agentId: string, taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode, pid?: number | null, status?: AgentStatus, startedAt?: Date, completedAt?: Date | null, baseDir?: string | null, parentSessionId?: string | null, workspaceDir?: string | null, cloudSessionId?: string | null, cloudProvider?: string | null, prUrl?: string | null, version?: string | null, remoteSessionId?: string | null, name?: string | null, after?: string[], effort?: EffortLevel | null, model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null);
     get isEditMode(): boolean;
     getAgentDir(): Promise<string>;
     /**
@@ -179,7 +180,7 @@ export declare class AgentManager {
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().

package/dist/lib/teams/agents.js

@@ -19,6 +19,7 @@ import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir } from '../state.js';
 import { AGENTS } from '../agents.js';
+import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
 // large inactive+purgeable cache the kernel will reclaim under pressure, so
@@ -171,7 +172,7 @@ export function captureProcessStartTime(pid) {
     }
 }
 /** Agent types the team runner supports. */
-const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode'];
+const TEAM_AGENT_TYPES = ['codex', 'cursor', 'gemini', 'claude', 'opencode', 'grok', 'antigravity'];
 // Suffix appended to all prompts to ensure agents provide a summary
 const PROMPT_SUFFIX = `
 
@@ -183,12 +184,17 @@ When you're done, provide a brief summary of:
 const CLAUDE_PLAN_MODE_PREFIX = `You are running in HEADLESS PLAN MODE. This mode works like normal plan mode with one exception: you cannot write to ~/.claude/plans/ directory. Instead of writing a plan file, output your complete plan/response as your final message.
 
 `;
-const VALID_MODES = ['plan', 'edit', 'full', 'auto'];
+// Canonical modes plus the historical `full` alias (rewritten to `skip` by
+// normalizeModeValue). Keep `full` listed so user-typed CLI flags and stored
+// metadata that pre-date the rename continue to parse.
+export const VALID_MODES = ['plan', 'edit', 'auto', 'skip', 'full'];
 function normalizeModeValue(modeValue) {
     if (!modeValue)
         return null;
     const normalized = modeValue.trim().toLowerCase();
-    if (VALID_MODES.includes(normalized)) {
+    if (normalized === 'full')
+        return 'skip';
+    if (['plan', 'edit', 'auto', 'skip'].includes(normalized)) {
         return normalized;
     }
     return null;
@@ -201,7 +207,7 @@ function defaultModeFromEnv() {
             return parsed;
         }
         if (rawValue) {
-            console.warn(`Invalid ${envVar}='${rawValue}'. Use 'plan' or 'edit'. Falling back to plan mode.`);
+            console.warn(`Invalid ${envVar}='${rawValue}'. Use plan, edit, auto, or skip. Falling back to plan mode.`);
         }
     }
     return 'plan';
@@ -253,12 +259,12 @@ function extractTimestamp(raw) {
 export function resolveMode(requestedMode, defaultMode = 'plan') {
     const normalizedDefault = normalizeModeValue(defaultMode);
     if (!normalizedDefault) {
-        throw new Error(`Invalid default mode '${defaultMode}'. Use 'plan' or 'edit'.`);
+        throw new Error(`Invalid default mode '${defaultMode}'. Use plan, edit, auto, or skip.`);
     }
     if (requestedMode !== null && requestedMode !== undefined) {
         const normalizedMode = normalizeModeValue(requestedMode);
         if (!normalizedMode) {
-            throw new Error(`Invalid mode '${requestedMode}'. Valid modes: 'plan' (read-only) or 'edit' (can write).`);
+            throw new Error(`Invalid mode '${requestedMode}'. Valid modes: plan (read-only), edit (can write), auto (smart classifier), skip (bypass all permissions). 'full' is accepted as alias for skip.`);
         }
         return normalizedMode;
     }
@@ -363,6 +369,11 @@ export class AgentProcess {
     // Pinned model for this teammate. When null, the agent's CLI picks its
     // own default (no --model forwarded).
     model = null;
+    // Profile target name when the teammate was added via `agents teams add
+    // <team> <profile>`. The launcher targets the profile name so env/keychain
+    // injection happens; agentType stays the underlying harness so event
+    // parsers and CLI availability checks keep working.
+    profileName = null;
     // Extra env vars passed through to the child process (from --env KEY=VALUE).
     envOverrides = null;
     // Factory task-type label. Drives planner fan-out. Null for plain teammates — no behavioral change.
@@ -378,13 +389,14 @@ export class AgentProcess {
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
-    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+    constructor(agentId, taskName, agentType, prompt, cwd = null, mode = 'plan', pid = null, status = AgentStatus.RUNNING, startedAt = new Date(), completedAt = null, baseDir = null, parentSessionId = null, workspaceDir = null, cloudSessionId = null, cloudProvider = null, prUrl = null, version = null, remoteSessionId = null, name = null, after = [], effort = null, model = null, envOverrides = null, taskType = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
         this.agentId = agentId;
         this.remoteSessionId = remoteSessionId;
         this.name = name;
         this.after = after;
         this.effort = effort;
         this.model = model;
+        this.profileName = profileName;
         this.envOverrides = envOverrides;
         this.taskType = taskType;
         this.cloudRepo = cloudRepo;
@@ -409,7 +421,9 @@ export class AgentProcess {
         this.version = version;
     }
     get isEditMode() {
-        return this.mode === 'edit' || this.mode === 'full';
+        // Any mode that can mutate the workspace counts as "edit mode" for the
+        // purposes of guarding read-only flows (plan-mode teammates).
+        return this.mode === 'edit' || this.mode === 'auto' || this.mode === 'skip';
     }
     async getAgentDir() {
         const base = this.baseDir || await getAgentsDir();
@@ -466,6 +480,7 @@ export class AgentProcess {
             after: this.after,
             effort: this.effort,
             model: this.model,
+            profile_name: this.profileName,
             env_overrides: this.envOverrides,
             task_type: this.taskType,
             cloud_repo: this.cloudRepo,
@@ -596,6 +611,7 @@ export class AgentProcess {
             after: this.after,
             effort: this.effort,
             model: this.model,
+            profile_name: this.profileName,
             env_overrides: this.envOverrides,
             task_type: this.taskType,
             cloud_repo: this.cloudRepo,
@@ -619,12 +635,16 @@ export class AgentProcess {
         try {
             const metaContent = await fs.readFile(metaPath, 'utf-8');
             const meta = JSON.parse(metaContent);
-            // Legacy teammates may have mode='ralph' or 'cloud' from before modes
-            // were narrowed. Coerce to the closest current mode so they still load.
+            // Legacy teammates may have mode='ralph', 'cloud', or 'full' from before
+            // modes were narrowed/renamed. Coerce to the closest current mode so they
+            // still load.
             const modeMap = {
+                plan: 'plan',
                 edit: 'edit',
-                full: 'full',
-                ralph: 'full', // ralph used the same "no-permission" flags as full
+                auto: 'auto',
+                skip: 'skip',
+                full: 'skip', // historical alias — `full` is the old name for `skip`
+                ralph: 'skip', // ralph used the same "no-permission" flags as full
                 cloud: 'edit', // cloud teammates had edit-level write access
             };
             const resolvedMode = modeMap[meta.mode] || 'plan';
@@ -637,7 +657,7 @@ export class AgentProcess {
                 : AgentStatus.RUNNING;
             const agent = new AgentProcess(meta.agent_id, meta.task_name || 'default', meta.agent_type, meta.prompt, meta.cwd || null, resolvedMode, meta.pid || null, resolvedStatus, new Date(meta.started_at), meta.completed_at ? new Date(meta.completed_at) : null, baseDir, meta.parent_session_id || null, meta.workspace_dir || null, meta.cloud_session_id || null, meta.cloud_provider || null, meta.pr_url || null, meta.version || null, meta.remote_session_id || null, meta.name || null, Array.isArray(meta.after) ? meta.after : [], meta.effort || null, meta.model || null, meta.env_overrides || null, meta.task_type && VALID_TASK_TYPES.includes(meta.task_type)
                 ? meta.task_type
-                : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null);
+                : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null, meta.profile_name || null);
             agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
             return agent;
         }
@@ -759,7 +779,7 @@ export class AgentManager {
         this.cleanupAgeDays = cleanupAgeDays;
         const resolvedDefaultMode = defaultMode ? normalizeModeValue(defaultMode) : defaultModeFromEnv();
         if (!resolvedDefaultMode) {
-            throw new Error(`Invalid default_mode '${defaultMode}'. Use 'plan' or 'edit'.`);
+            throw new Error(`Invalid default_mode '${defaultMode}'. Use plan, edit, auto, or skip.`);
         }
         this.defaultMode = resolvedDefaultMode;
         this.initPromise = this.doInitialize();
@@ -875,7 +895,7 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Enforce: teammate names are unique within a team.
@@ -922,6 +942,9 @@ export class AgentManager {
         // dispatched via the cloud provider and passed us the provider + session.
         const isCloudBacked = Boolean(cloudProvider);
         if (!isCloudBacked) {
+            // Profile-backed teammates still spawn through `agents run`, which
+            // resolves the profile to its host harness — so the CLI we need to be
+            // present is the underlying agentType, not the profile name.
             const [available, pathOrError] = checkCliAvailable(agentType);
             if (!available) {
                 throw new Error(pathOrError || 'CLI tool not available');
@@ -934,7 +957,7 @@ export class AgentManager {
         const initialStatus = isStaged || !isCloudBacked
             ? AgentStatus.PENDING
             : AgentStatus.RUNNING;
-        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath);
+        const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -971,7 +994,7 @@ export class AgentManager {
         // forwarded). Effort is a separate knob wired into buildReasoningFlags
         // inside buildCommand.
         const resolvedModel = agent.model ?? null;
-        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version);
+        const cmd = this.buildCommand(agent.agentType, agent.prompt, agent.mode, resolvedModel, agent.cwd, agent.agentId, effort, agent.version, agent.profileName);
         debug(`Launching ${agent.agentType} agent ${agent.agentId} [${agent.mode}]: ${cmd.slice(0, 3).join(' ')}...`);
         try {
             const stdoutPath = await agent.getStdoutPath();
@@ -982,8 +1005,8 @@ export class AgentManager {
                 cwd: agent.cwd || undefined,
                 detached: true,
                 env: agent.envOverrides
-                    ? { ...process.env, ...agent.envOverrides }
-                    : process.env,
+                    ? { ...sanitizeProcessEnv(process.env), ...agent.envOverrides }
+                    : sanitizeProcessEnv(process.env),
             });
             childProcess.unref();
             stdoutFile.close().catch(() => { });
@@ -1055,15 +1078,18 @@ export class AgentManager {
      * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
      * and reads stream-json events off stdout.
      */
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null) {
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
         // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
         // plan-mode restrictions) and a universal summary suffix. These are
         // team-specific prompt scaffolding — `agents run` does not apply them.
         let fullPrompt = prompt + PROMPT_SUFFIX;
-        if (agentType === 'claude' && mode !== 'edit') {
+        if (agentType === 'claude' && mode === 'plan') {
             fullPrompt = CLAUDE_PLAN_MODE_PREFIX + fullPrompt;
         }
-        const target = version ? `${agentType}@${version}` : agentType;
+        // Profile target takes precedence — `agents run <profile>` resolves the
+        // host harness, version pin, and env injection in one place. Plain
+        // version pins only apply when no profile is selected.
+        const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
         const agentsCli = process.argv[1];
         const cmd = [
             process.execPath,

package/dist/lib/teams/api.d.ts

@@ -13,6 +13,7 @@ export interface SpawnResult {
     status: string;
     started_at: string;
     version?: string | null;
+    profile_name?: string | null;
     remote_session_id?: string | null;
     name?: string | null;
     after?: string[];
@@ -88,7 +89,7 @@ export interface TasksResult {
     tasks: TaskInfo[];
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null): Promise<SpawnResult>;
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<SpawnResult>;
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;

package/dist/lib/teams/api.js

@@ -56,12 +56,12 @@ function recentToolCalls(events, max = 10) {
     }));
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null) {
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
-    debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}...`);
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath);
+    debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}${profileName ? ` profile=${profileName}` : ''}...`);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,
@@ -70,6 +70,7 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
         status: agent.status,
         started_at: agent.startedAt.toISOString(),
         version: agent.version,
+        profile_name: agent.profileName,
         remote_session_id: agent.remoteSessionId,
         name: agent.name,
         after: agent.after,

package/dist/lib/teams/parsers.d.ts

@@ -1,5 +1,5 @@
 /** Supported agent CLI types for team spawning. */
-export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode';
+export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity';
 /** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export declare function normalizeEvents(agentType: AgentType, raw: any): any[];
 /** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */