@phnx-labs/agents-cli 1.20.59 → 1.20.61

package/dist/lib/permissions.js

@@ -306,14 +306,21 @@ export function buildPermissionsFromGroups(groupNames) {
             // Matches lines like: - "Bash(git *)" or   - "WebFetch(domain:example.com)"
             // Handles nested quotes that break YAML parsers
             const lines = content.split('\n');
+            let section = null;
             for (const line of lines) {
+                const sectionMatch = line.match(/^\s*(allow|deny)\s*:\s*(?:#.*)?$/);
+                if (sectionMatch) {
+                    section = sectionMatch[1];
+                    continue;
+                }
                 // Match: optional whitespace, dash, whitespace, quote, content, quote
                 // Use greedy match to capture everything between first and last quote
                 const match = line.match(/^\s*-\s*"(.+)"$/);
                 if (match) {
                     const rule = match[1];
-                    // 99-deny group rules go to deny, others to allow
-                    if (groupName === '99-deny' || groupName.includes('-deny')) {
+                    // 99-deny group rules go to deny, others follow their YAML section.
+                    // Legacy group files used bare lists with no section; keep those as allow.
+                    if (section === 'deny' || groupName === '99-deny' || groupName.includes('-deny')) {
                         allDeny.push(rule);
                     }
                     else {
@@ -486,32 +493,40 @@ function parseCanonicalPattern(permission) {
 const BLANKET_BASH_FORMS = new Set(['Bash', 'Bash(*)', 'Bash(**)']);
 /**
  * Convert canonical permission set to Gemini format.
- * Gemini reads tool allow-lists from settings.json under `tools.allowed`.
- * Bash permissions map to run_shell_command(prefix) — the prefix is extracted
- * from the canonical "Bash(cmd:*)" pattern by stripping the trailing ":*".
- * Blanket Bash grants map to bare "run_shell_command" (no prefix filter).
+ * Gemini reads tool allow/deny lists from settings.json under
+ * `tools.core` / `tools.exclude`. Bash permissions map to ShellTool(pattern).
+ * Blanket Bash grants map to bare "ShellTool" (no command filter).
  * Non-Bash tool patterns are skipped; Gemini uses different tool names.
  */
 export function convertToGeminiFormat(set) {
-    const allowed = new Set();
-    for (const perm of set.allow) {
-        if (BLANKET_BASH_FORMS.has(perm)) {
-            allowed.add('run_shell_command');
-            continue;
-        }
-        const parsed = parseCanonicalPattern(perm);
-        if (!parsed || parsed.tool !== 'bash')
-            continue;
-        const colonIdx = parsed.pattern.lastIndexOf(':');
-        const prefix = colonIdx > 0 ? parsed.pattern.slice(0, colonIdx) : parsed.pattern;
-        if (prefix === '*' || prefix === '**') {
-            allowed.add('run_shell_command');
-        }
-        else {
-            allowed.add(`run_shell_command(${prefix})`);
+    const serialize = (permissions) => {
+        const tools = new Set();
+        for (const perm of permissions) {
+            if (BLANKET_BASH_FORMS.has(perm)) {
+                tools.add('ShellTool');
+                continue;
+            }
+            const parsed = parseCanonicalPattern(perm);
+            if (!parsed || parsed.tool !== 'bash')
+                continue;
+            const command = normalizeBashPattern(parsed.pattern);
+            if (command === '*') {
+                tools.add('ShellTool');
+            }
+            else {
+                tools.add(`ShellTool(${command})`);
+            }
         }
-    }
-    return { tools: { allowed: Array.from(allowed) } };
+        return Array.from(tools);
+    };
+    const core = serialize(set.allow);
+    const exclude = serialize(set.deny ?? []);
+    return {
+        tools: {
+            core,
+            ...(exclude.length ? { exclude } : {}),
+        },
+    };
 }
 /**
  * Strip Claude's `:*` subcommand-wildcard suffix and return a space-glob form.
@@ -596,6 +611,49 @@ const ANTIGRAVITY_ACTION_BY_TOOL = {
     write: 'write_file',
     webfetch: 'read_url',
 };
+const GOOSE_TOOL_BY_CANONICAL = {
+    bash: 'developer__shell',
+    read: 'developer__text_editor',
+    write: 'developer__text_editor',
+    edit: 'developer__text_editor',
+    grep: 'developer__analyze',
+    glob: 'developer__analyze',
+    webfetch: 'developer__fetch',
+    mcp: undefined,
+};
+function canonicalToGooseTool(permission) {
+    if (BLANKET_BASH_FORMS.has(permission))
+        return 'developer__shell';
+    const parsed = parseCanonicalPattern(permission);
+    if (!parsed)
+        return null;
+    return GOOSE_TOOL_BY_CANONICAL[parsed.tool] ?? null;
+}
+/** Convert canonical permissions to Goose's per-tool permission.yaml shape. */
+export function convertToGooseFormat(set) {
+    const alwaysAllow = new Set();
+    const neverAllow = new Set();
+    for (const permission of set.allow) {
+        const tool = canonicalToGooseTool(permission);
+        if (tool)
+            alwaysAllow.add(tool);
+    }
+    for (const permission of set.deny ?? []) {
+        const tool = canonicalToGooseTool(permission);
+        if (tool)
+            neverAllow.add(tool);
+    }
+    for (const tool of neverAllow) {
+        alwaysAllow.delete(tool);
+    }
+    return {
+        user: {
+            always_allow: Array.from(alwaysAllow).sort(),
+            ask_before: [],
+            never_allow: Array.from(neverAllow).sort(),
+        },
+    };
+}
 /**
  * Convert canonical permission set to Grok format.
  * Grok reads ~/.grok/config.toml with
@@ -1274,17 +1332,29 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             const geminiPerms = convertToGeminiFormat(set);
             const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
             updateGeminiSettings(settingsPath, (settings) => {
-                // Remove stale permissions key written by earlier versions of this serializer.
+                // Remove stale keys written by earlier serializer versions:
+                // top-level `permissions`, and Gemini's pre-core/exclude `tools.allowed`.
                 delete settings.permissions;
                 const tools = (typeof settings.tools === 'object' && settings.tools !== null && !Array.isArray(settings.tools))
                     ? settings.tools
                     : {};
+                delete tools.allowed;
                 if (merge) {
-                    const existing = Array.isArray(tools.allowed) ? tools.allowed : [];
-                    tools.allowed = Array.from(new Set([...existing, ...geminiPerms.tools.allowed]));
+                    const existingCore = Array.isArray(tools.core) ? tools.core : [];
+                    const existingExclude = Array.isArray(tools.exclude) ? tools.exclude : [];
+                    tools.core = Array.from(new Set([...existingCore, ...geminiPerms.tools.core]));
+                    const mergedExclude = Array.from(new Set([...existingExclude, ...(geminiPerms.tools.exclude ?? [])]));
+                    if (mergedExclude.length)
+                        tools.exclude = mergedExclude;
+                    else
+                        delete tools.exclude;
                 }
                 else {
-                    tools.allowed = geminiPerms.tools.allowed;
+                    tools.core = geminiPerms.tools.core;
+                    if (geminiPerms.tools.exclude?.length)
+                        tools.exclude = geminiPerms.tools.exclude;
+                    else
+                        delete tools.exclude;
                 }
                 settings.tools = tools;
             });
@@ -1349,6 +1419,47 @@ export function applyPermissionsToVersion(agentId, set, versionHome, merge = tru
             fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
             return { success: true };
         }
+        if (agentId === 'goose') {
+            const permissionsPath = path.join(versionHome, '.config', 'goose', 'permission.yaml');
+            let config = {};
+            if (fs.existsSync(permissionsPath)) {
+                const parsed = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    config = parsed;
+                }
+            }
+            const converted = convertToGooseFormat(set).user;
+            const user = (typeof config.user === 'object' && config.user !== null && !Array.isArray(config.user))
+                ? config.user
+                : {};
+            const currentAlways = Array.isArray(user.always_allow) ? user.always_allow.filter((v) => typeof v === 'string') : [];
+            const currentAsk = Array.isArray(user.ask_before) ? user.ask_before.filter((v) => typeof v === 'string') : [];
+            const currentNever = Array.isArray(user.never_allow) ? user.never_allow.filter((v) => typeof v === 'string') : [];
+            if (merge) {
+                const incomingAlways = new Set(converted.always_allow);
+                const incomingNever = new Set(converted.never_allow);
+                const touched = new Set([...incomingAlways, ...incomingNever]);
+                const always = new Set(currentAlways.filter(tool => !touched.has(tool)));
+                const ask = new Set(currentAsk.filter(tool => !touched.has(tool)));
+                const never = new Set(currentNever.filter(tool => !touched.has(tool)));
+                for (const tool of incomingAlways)
+                    always.add(tool);
+                for (const tool of incomingNever)
+                    never.add(tool);
+                user.always_allow = Array.from(always).sort();
+                user.ask_before = Array.from(ask).sort();
+                user.never_allow = Array.from(never).sort();
+            }
+            else {
+                user.always_allow = converted.always_allow;
+                user.ask_before = converted.ask_before;
+                user.never_allow = converted.never_allow;
+            }
+            config.user = user;
+            fs.mkdirSync(path.dirname(permissionsPath), { recursive: true });
+            fs.writeFileSync(permissionsPath, yaml.stringify(config), 'utf-8');
+            return { success: true };
+        }
         if (agentId === 'kimi') {
             const configPath = path.join(versionHome, '.kimi-code', 'config.toml');
             let config = {};

package/dist/lib/plugins.d.ts

@@ -191,6 +191,14 @@ export declare function resolveOpenCodePluginSources(pluginRoot: string): string
 export declare function installOpenCodePlugin(plugin: DiscoveredPlugin, versionHome: string): boolean;
 export declare function isOpenCodePluginInstalled(pluginName: string, versionHome: string): boolean;
 export declare function removeOpenCodePlugin(pluginName: string, versionHome: string): boolean;
+/**
+ * Gemini CLI extensions live under `$HOME/.gemini/extensions/<name>/` and
+ * require a `gemini-extension.json` manifest at the extension root.
+ */
+export declare function geminiExtensionsDir(versionHome: string): string;
+export declare function installGeminiPlugin(plugin: DiscoveredPlugin, versionHome: string): boolean;
+export declare function isGeminiPluginInstalled(pluginName: string, versionHome: string): boolean;
+export declare function removeGeminiPlugin(pluginName: string, versionHome: string): boolean;
 /**
  * Goose auto-discovers Open Plugins at `$HOME/.agents/plugins/<name>/`.
  * Under agents-cli version isolation HOME is the version home, so we install to:

package/dist/lib/plugins.js

@@ -21,6 +21,7 @@ import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './com
 import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, registerDroidInstalledPlugin, unregisterDroidInstalledPlugin, isDroidPluginInstalled, registerCopilotInstalledPlugin, unregisterCopilotInstalledPlugin, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
+const GEMINI_EXTENSION_MANIFEST_FILE = 'gemini-extension.json';
 const USER_CONFIG_FILE = '.user-config.json';
 const SOURCE_FILE = '.source';
 export const PLUGIN_EXEC_SURFACE_LABELS = {
@@ -502,6 +503,27 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
             result.skills.push(plugin.name);
         return result;
     }
+    // Gemini CLI loads extensions from $HOME/.gemini/extensions/<name>/.
+    // Copy the plugin bundle as an extension and synthesize gemini-extension.json.
+    if (agent === 'gemini') {
+        const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
+        if (!enablePlugin) {
+            return result;
+        }
+        const ok = installGeminiPlugin(plugin, versionHome);
+        result.success = ok;
+        if (ok) {
+            result.skills = plugin.skills.map(s => `${plugin.name}:${s}`);
+            result.commands = plugin.commands.map(c => `${plugin.name}:${c}`);
+            result.agentDefs = plugin.agentDefs.map(a => `${plugin.name}:${a}`);
+            result.bin = plugin.bin;
+            result.hooks = plugin.hooks;
+            result.mcp = plugin.hasMcp;
+            result.settings = plugin.hasSettings;
+            result.permissions = pluginHasPermissions(plugin);
+        }
+        return result;
+    }
     // Goose loads Open Plugins from $HOME/.agents/plugins/<name>/ (same layout as
     // agents-cli's source tree). Under the shim HOME is the version home.
     if (agent === 'goose') {
@@ -901,6 +923,82 @@ export function removeOpenCodePlugin(pluginName, versionHome) {
     }
     return removed;
 }
+// ─── Gemini extensions ───────────────────────────────────────────────────────
+/**
+ * Gemini CLI extensions live under `$HOME/.gemini/extensions/<name>/` and
+ * require a `gemini-extension.json` manifest at the extension root.
+ */
+export function geminiExtensionsDir(versionHome) {
+    return path.join(versionHome, '.gemini', 'extensions');
+}
+function readPluginMcpConfigForGemini(pluginRoot) {
+    const mcpPath = path.join(pluginRoot, '.mcp.json');
+    if (!fs.existsSync(mcpPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+        if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object')
+            return undefined;
+        return rewriteGeminiExtensionVars(parsed.mcpServers);
+    }
+    catch {
+        return undefined;
+    }
+}
+function rewriteGeminiExtensionVars(value) {
+    if (typeof value === 'string') {
+        return value
+            .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, '${extensionPath}')
+            .replace(/\$\{CLAUDE_PLUGIN_DATA\}/g, '${extensionPath}/.data');
+    }
+    if (Array.isArray(value))
+        return value.map(rewriteGeminiExtensionVars);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rewriteGeminiExtensionVars(item)]));
+    }
+    return value;
+}
+function writeGeminiExtensionManifest(plugin, destRoot) {
+    const manifest = {
+        name: plugin.manifest.name,
+        version: plugin.manifest.version,
+        description: plugin.manifest.description,
+    };
+    const mcpServers = readPluginMcpConfigForGemini(destRoot);
+    if (mcpServers && Object.keys(mcpServers).length > 0) {
+        manifest.mcpServers = mcpServers;
+    }
+    fs.writeFileSync(path.join(destRoot, GEMINI_EXTENSION_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+}
+export function installGeminiPlugin(plugin, versionHome) {
+    const destRoot = path.join(geminiExtensionsDir(versionHome), plugin.name);
+    try {
+        if (fs.existsSync(destRoot)) {
+            fs.rmSync(destRoot, { recursive: true, force: true });
+        }
+        fs.cpSync(plugin.root, destRoot, { recursive: true });
+        const userConfig = loadUserConfig(plugin.name);
+        if (Object.keys(userConfig).length > 0) {
+            expandUserConfigInDir(destRoot, userConfig);
+        }
+        writeGeminiExtensionManifest(plugin, destRoot);
+        fs.writeFileSync(path.join(destRoot, '.agents-cli-managed'), `plugin=${plugin.name}\n`, 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function isGeminiPluginInstalled(pluginName, versionHome) {
+    return fs.existsSync(path.join(geminiExtensionsDir(versionHome), pluginName, GEMINI_EXTENSION_MANIFEST_FILE));
+}
+export function removeGeminiPlugin(pluginName, versionHome) {
+    const destRoot = path.join(geminiExtensionsDir(versionHome), pluginName);
+    if (!fs.existsSync(destRoot))
+        return false;
+    fs.rmSync(destRoot, { recursive: true, force: true });
+    return true;
+}
 // ─── Goose plugins (Open Plugins under .agents/plugins/) ─────────────────────
 /**
  * Goose auto-discovers Open Plugins at `$HOME/.agents/plugins/<name>/`.
@@ -949,6 +1047,9 @@ export function isPluginSynced(plugin, agent, versionHome) {
     if (agent === 'opencode') {
         return isOpenCodePluginInstalled(plugin.name, versionHome);
     }
+    if (agent === 'gemini') {
+        return isGeminiPluginInstalled(plugin.name, versionHome);
+    }
     if (agent === 'goose') {
         return isGoosePluginInstalled(plugin.name, versionHome);
     }
@@ -986,6 +1087,13 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
         }
         return result;
     }
+    // Gemini: remove extension directory from ~/.gemini/extensions/.
+    if (agent === 'gemini') {
+        if (removeGeminiPlugin(pluginName, versionHome)) {
+            result.skills.push(pluginName);
+        }
+        return result;
+    }
     // Goose: remove Open Plugin directory from versionHome/.agents/plugins/.
     if (agent === 'goose') {
         if (removeGoosePlugin(pluginName, versionHome)) {

package/dist/lib/resources/permissions.d.ts

@@ -4,7 +4,7 @@
  * Permissions are stored as YAML files in permissions/ directories at each layer.
  * Resolution: project > user > system (higher layer wins on name conflict).
  * Unlike other resources, permissions merge into agent-specific config files
- * (Claude: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
+ * (Claude/Gemini: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
  */
 import type { ResourceHandler } from './types.js';
 import type { PermissionSet } from '../types.js';

package/dist/lib/resources/permissions.js

@@ -4,7 +4,7 @@
  * Permissions are stored as YAML files in permissions/ directories at each layer.
  * Resolution: project > user > system (higher layer wins on name conflict).
  * Unlike other resources, permissions merge into agent-specific config files
- * (Claude: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
+ * (Claude/Gemini: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -65,6 +65,8 @@ function getAgentConfigPath(agent, versionHome) {
             return path.join(versionHome, '.claude', 'settings.json');
         case 'codex':
             return path.join(versionHome, '.codex', 'config.toml');
+        case 'gemini':
+            return path.join(versionHome, '.gemini', 'settings.json');
         case 'opencode':
             return path.join(versionHome, '.config', 'opencode', 'opencode.jsonc');
         case 'kimi':
@@ -73,6 +75,8 @@ function getAgentConfigPath(agent, versionHome) {
             return path.join(versionHome, '.factory', 'settings.json');
         case 'kiro':
             return path.join(versionHome, '.kiro', 'settings', 'permissions.yaml');
+        case 'goose':
+            return path.join(versionHome, '.config', 'goose', 'permission.yaml');
         default:
             return null;
     }

package/dist/lib/resources/types.d.ts

@@ -5,7 +5,7 @@
  * - Union: All resources from all layers are combined
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'kiro' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'forge';
 export type Layer = 'system' | 'user' | 'project';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */

package/dist/lib/routines.d.ts

@@ -75,6 +75,13 @@ export interface JobConfig {
     version?: string;
     runOnce?: boolean;
     endAt?: string;
+    /**
+     * When set, the job resumes this existing agent session id at fire time
+     * (`agents run <agent> --resume <id>`) instead of starting a fresh conversation,
+     * so the actual session reopens with full context and `prompt` becomes its next
+     * turn. Powers self-scheduled wake-ups (e.g. /hibernate). claude/codex only.
+     */
+    resume?: string;
     /** When set, executeJob runs this job through the loop driver instead of once. */
     loop?: LoopConfig;
 }
@@ -138,6 +145,22 @@ export declare function readJob(name: string, cwd?: string): JobConfig | null;
  * name, the write fails explicitly so we never choose or drop a sibling.
  */
 export declare function writeJob(config: JobConfig): void;
+/**
+ * Serialize a job config, preserving the on-disk formatting of an existing file.
+ *
+ * A full `yaml.stringify(config)` re-emits the whole document — restyling every
+ * scalar (unquoting `schedule`, re-wrapping the folded `prompt` block, reordering
+ * keys). When a routine is only being toggled (pause/resume) or re-pinned
+ * (`devices --set`), that rewrites the entire file, leaving the git-backed
+ * `~/.agents` tree perpetually dirty so `agents repo pull` refuses to sync across
+ * the fleet. To keep the diff to the field that actually changed, we edit the
+ * existing document in place and only re-render touched nodes; untouched nodes
+ * (notably the large `prompt` block) keep their byte-for-byte formatting.
+ *
+ * `existingText` is the current file contents, or null for a new file. New,
+ * unparseable, and non-mapping documents fall back to canonical `yaml.stringify`.
+ */
+export declare function serializeJob(output: Record<string, unknown>, existingText: string | null): string;
 /** Delete a job config file by name. Returns true if the file existed. */
 export declare function deleteJob(name: string): boolean;
 /** Enable or disable a job by name. */

package/dist/lib/routines.js

@@ -187,7 +187,52 @@ export function writeJob(config) {
     const devArr = output.devices;
     if (!devArr || devArr.length === 0)
         delete output.devices;
-    atomicWriteFileSync(filePath, yaml.stringify(output));
+    let existingText = null;
+    if (ymlExists || yamlExists) {
+        try {
+            existingText = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            existingText = null;
+        }
+    }
+    atomicWriteFileSync(filePath, serializeJob(output, existingText));
+}
+/**
+ * Serialize a job config, preserving the on-disk formatting of an existing file.
+ *
+ * A full `yaml.stringify(config)` re-emits the whole document — restyling every
+ * scalar (unquoting `schedule`, re-wrapping the folded `prompt` block, reordering
+ * keys). When a routine is only being toggled (pause/resume) or re-pinned
+ * (`devices --set`), that rewrites the entire file, leaving the git-backed
+ * `~/.agents` tree perpetually dirty so `agents repo pull` refuses to sync across
+ * the fleet. To keep the diff to the field that actually changed, we edit the
+ * existing document in place and only re-render touched nodes; untouched nodes
+ * (notably the large `prompt` block) keep their byte-for-byte formatting.
+ *
+ * `existingText` is the current file contents, or null for a new file. New,
+ * unparseable, and non-mapping documents fall back to canonical `yaml.stringify`.
+ */
+export function serializeJob(output, existingText) {
+    if (existingText == null)
+        return yaml.stringify(output);
+    const doc = yaml.parseDocument(existingText);
+    if (doc.errors.length > 0 || !yaml.isMap(doc.contents))
+        return yaml.stringify(output);
+    const existing = (doc.toJS() ?? {});
+    // Update or add only the keys that actually changed; leave the rest untouched
+    // so their original formatting is preserved.
+    for (const [key, value] of Object.entries(output)) {
+        if (JSON.stringify(existing[key]) !== JSON.stringify(value))
+            doc.set(key, value);
+    }
+    // Drop keys that no longer belong (e.g. an omitted default, or `devices`
+    // cleared back to fleet-wide).
+    for (const key of Object.keys(existing)) {
+        if (!(key in output))
+            doc.delete(key);
+    }
+    return doc.toString();
 }
 /** Delete a job config file by name. Returns true if the file existed. */
 export function deleteJob(name) {
@@ -253,6 +298,24 @@ export function validateJob(config) {
             errors.push('workflow must be a lowercase alphanumeric name (hyphens and underscores allowed, e.g. autodev)');
         }
     }
+    if (config.resume !== undefined) {
+        // Only claude/codex support native `--resume`; other agents would emit a resume
+        // flag they don't understand. Resume reopens an agent session, so it is
+        // incompatible with workflow and loop jobs (which have no single session to reopen).
+        const RESUMABLE_AGENTS = ['claude', 'codex'];
+        if (typeof config.resume !== 'string' || config.resume.trim() === '') {
+            errors.push('resume must be a non-empty session id string');
+        }
+        if (hasWorkflow) {
+            errors.push('resume cannot be combined with workflow (resume reopens an existing agent session)');
+        }
+        if (config.loop) {
+            errors.push('resume cannot be combined with loop');
+        }
+        if (hasAgent && config.agent && !RESUMABLE_AGENTS.includes(config.agent)) {
+            errors.push(`resume is only supported for agents with native --resume (${RESUMABLE_AGENTS.join(', ')}); got '${config.agent}'`);
+        }
+    }
     if (config.mode && !['plan', 'edit', 'auto', 'skip', 'full'].includes(config.mode)) {
         errors.push("mode must be plan, edit, auto, or skip ('full' accepted as alias for skip)");
     }

package/dist/lib/runner.d.ts

@@ -50,6 +50,13 @@ export declare function resolveRoutineLaunch(config: JobConfig, cwd?: string): P
  * surface as "agents: no version of X configured".
  */
 export declare function pinJobBinary(cmd: string[], agent: AgentId, version: string | undefined): string[];
+/**
+ * Whether a job's command is dispatched through `agents run` (so `cmd[0] === 'agents'`)
+ * rather than the agent binary directly. True for workflow jobs and for resume jobs.
+ * Such commands must NOT be binary-pinned (pinning rewrites cmd[0] to the agent binary,
+ * producing a broken `<binary> run …`) and must not receive a version-pinned spawn env.
+ */
+export declare function dispatchesViaAgentsRun(config: Pick<JobConfig, 'workflow' | 'resume'>): boolean;
 /**
  * Merge sandbox/base env with the canonical per-version exec env
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation

package/dist/lib/runner.js

@@ -44,6 +44,14 @@ export function buildJobCommand(config, resolvedPrompt) {
         const cmd = ['agents', 'run', config.workflow, resolvedPrompt, '--mode', config.mode];
         return cmd;
     }
+    // Resume branch: reopen an EXISTING session via `agents run <agent> --resume <id>`
+    // instead of starting fresh. The real session resumes with its full prior context
+    // (index-based lookup, cwd-independent) and `resolvedPrompt` becomes its next turn —
+    // so a self-scheduled wake (e.g. /hibernate) is handled by the session that scheduled
+    // it, not a fresh, context-less agent that would refuse an "opaque" instruction.
+    if (config.resume) {
+        return ['agents', 'run', config.agent, '--resume', config.resume, resolvedPrompt, '--mode', config.mode];
+    }
     const template = AGENT_COMMANDS[config.agent];
     if (!template) {
         throw new Error(`Unsupported agent for daemon jobs: ${config.agent}`);
@@ -263,6 +271,15 @@ export function pinJobBinary(cmd, agent, version) {
     next[0] = binary;
     return next;
 }
+/**
+ * Whether a job's command is dispatched through `agents run` (so `cmd[0] === 'agents'`)
+ * rather than the agent binary directly. True for workflow jobs and for resume jobs.
+ * Such commands must NOT be binary-pinned (pinning rewrites cmd[0] to the agent binary,
+ * producing a broken `<binary> run …`) and must not receive a version-pinned spawn env.
+ */
+export function dispatchesViaAgentsRun(config) {
+    return Boolean(config.workflow || config.resume);
+}
 /**
  * Merge sandbox/base env with the canonical per-version exec env
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
@@ -394,7 +411,11 @@ export async function executeJob(config, deps) {
         schedule: config.schedule,
     });
     const resolvedPrompt = resolveJobPrompt(config);
-    const useSandbox = config.sandbox !== false;
+    // Resume must run against the REAL home: `--resume <id>` resolves the session from
+    // the agent's config dir, and the sandbox overlay home has only a freshly-generated
+    // config with no session store. So a resume job is never sandboxed, regardless of
+    // `config.sandbox` (see the resume branch in buildJobCommand).
+    const useSandbox = config.sandbox !== false && !config.resume;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
@@ -470,10 +491,11 @@ export async function executeJob(config, deps) {
         if (i === 0) {
             process.stderr.write(`[agents] routine ${config.name}: running ${label}\n`);
         }
-        const cmd = config.workflow
+        const viaAgentsRun = dispatchesViaAgentsRun(config);
+        const cmd = viaAgentsRun
             ? baseCmd
             : pinJobBinary(baseCmd, attemptAgent, attemptVersion);
-        const spawnEnv = config.workflow
+        const spawnEnv = viaAgentsRun
             ? (() => {
                 const e = { ...baseEnv };
                 if (config.timezone)
@@ -553,10 +575,16 @@ export async function executeJobDetached(config) {
     const version = launch.chain[0]?.version ?? config.version;
     const resolvedPrompt = resolveJobPrompt(config);
     let cmd = buildJobCommand(config, resolvedPrompt);
-    if (!config.workflow && version) {
+    // workflow AND resume dispatch through `agents run` — never binary-pin them (pinning
+    // rewrites cmd[0] to the agent binary → broken `<binary> run …`).
+    if (!dispatchesViaAgentsRun(config) && version) {
         cmd = pinJobBinary(cmd, config.agent, version);
     }
-    const useSandbox = config.sandbox !== false;
+    // Resume must run against the REAL home: `--resume <id>` resolves the session from
+    // the agent's config dir, and the sandbox overlay home has only a freshly-generated
+    // config with no session store. So a resume job is never sandboxed, regardless of
+    // `config.sandbox` (see the resume branch in buildJobCommand).
+    const useSandbox = config.sandbox !== false && !config.resume;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
@@ -566,7 +594,7 @@ export async function executeJobDetached(config) {
     const baseEnv = useSandbox
         ? buildSpawnEnv(overlayHome)
         : { ...process.env };
-    const spawnEnv = config.workflow
+    const spawnEnv = dispatchesViaAgentsRun(config)
         ? (() => {
             const e = { ...baseEnv };
             if (config.timezone)