@phnx-labs/agents-cli 1.22.14 → 1.22.16

package/dist/lib/channels/send.js

@@ -1,3 +1,4 @@
+import { getOwnerNotifyFromHumans } from '../humans.js';
 import { registerBuiltinProviders } from './providers/index.js';
 import { resolveTransport } from './resolve.js';
 const OWNER_ALIAS = 'owner';
@@ -16,8 +17,14 @@ export function composeSendText(text, urls) {
         return body;
     return body ? `${body}\n${extra.join('\n')}` : extra.join('\n');
 }
-/** Read notify.owner; null when either field is missing. */
+/**
+ * Read the owner destination; humans.yaml is the primary source, agents.yaml
+ * notify.owner is the fallback. Returns null when neither is set.
+ */
 export function readOwnerDest(meta) {
+    const humansOwner = getOwnerNotifyFromHumans();
+    if (humansOwner)
+        return humansOwner;
     const owner = meta.notify?.owner;
     const channel = owner?.channel?.trim();
     const to = owner?.to?.trim();
@@ -48,15 +55,16 @@ export function resolveSendEnvelope(input, meta) {
         };
     }
     // Owner defaults fill only missing fields (and expand the bare "owner" alias).
-    // Explicit --channel/--to always win; a complete notify.owner is NOT required
-    // when both flags are already set (same merge-then-require shape as main).
-    const ownerCfg = meta.notify?.owner;
-    const ownerChannel = ownerCfg?.channel?.trim() || '';
-    const ownerTo = ownerCfg?.to?.trim() || '';
+    // humans.yaml is the primary source; notify.owner in agents.yaml is the
+    // fallback for the migration window. Explicit --channel/--to always win.
     let channel = (input.channel ?? '').trim();
     let to = (input.to ?? '').trim();
     const usedOwnerAlias = isOwnerAlias(to);
     if (input.ownerMode || usedOwnerAlias) {
+        const humansOwner = getOwnerNotifyFromHumans();
+        const fallbackOwner = meta.notify?.owner;
+        const ownerChannel = humansOwner?.channel ?? fallbackOwner?.channel?.trim() ?? '';
+        const ownerTo = humansOwner?.to ?? fallbackOwner?.to?.trim() ?? '';
         if (!channel)
             channel = ownerChannel;
         if (!to || usedOwnerAlias)
@@ -64,7 +72,7 @@ export function resolveSendEnvelope(input, meta) {
     }
     if (!channel || !to) {
         const hint = input.ownerMode || usedOwnerAlias
-            ? 'Set notify.owner.{channel,to} in agents.yaml, or pass --channel and --to explicitly.'
+            ? 'Set notify.{channel,to} in humans.yaml (or notify.owner in agents.yaml), or pass --channel and --to explicitly.'
             : 'Need --channel and --to (or --to owner with notify.owner configured). ' +
                 'Example: agents send --channel desktop --to local --text "hi"';
         return { ok: false, error: hint };

package/dist/lib/devices/doctor-findings.d.ts

@@ -8,7 +8,21 @@ import type { FleetDivergence, FleetVersionSignIn } from './fleet-divergence.js'
 export type FindingSeverity = 'critical' | 'warning';
 /** A machine-stable class for a finding — drives {@link remediationFor} and lets
  *  the JSON consumer group by kind. */
+/** Every finding class. Severity is NOT annotated here — {@link FINDING_SEVERITY}
+ *  below owns it, and a second copy in these comments is a fourth place to drift. */
 export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "exec-policy", "stale-cli"];
+/**
+ * The severity each kind is emitted with - the SINGLE source of truth, read by
+ * the builders below and asserted against both prose rubrics by
+ * `doctor-findings.test.ts`.
+ *
+ * It exists because severity drifted: the rubrics claimed `never-synced` and
+ * `duplicate-hook-drift` were critical for three days after RUSH-2162 downgraded
+ * them, and the exhaustiveness test missed it because it only checked that a kind
+ * was *named* in the rubric, not which bucket it sat in. Change a severity HERE
+ * and the test names the docs that must move with it.
+ */
+export declare const FINDING_SEVERITY: Record<FindingKind, FindingSeverity>;
 /** A machine-stable class for a finding. Derived from the runtime list above so
  *  the rubric test can enumerate every kind. */
 export type FindingKind = typeof ALL_FINDING_KINDS[number];

package/dist/lib/devices/doctor-findings.js

@@ -18,13 +18,14 @@
  * with. Keep this list exhaustive; a kind missing from it is a doc that lies.
  *   CRITICAL — logged-out (provable) · missing-hook · missing-plugin ·
  *              unwired-hook (a hook on disk that settings.json never fires) ·
- *              never-synced WHEN the version's declared resources are absent ·
- *              duplicate-hook-drift (copies that DIFFER) · cli-missing.
+ *              cli-missing.
  *   WARNING  — logout-unprovable (hedged) · missing-resource · content-drift ·
- *              stale · never-synced when the version declares nothing to miss ·
- *              repo-behind · repo-drift · version-skew · fleet-resource-gap ·
- *              orphan · duplicate-hook (identical copies) · host-cli-missing ·
- *              host-cli-invalid · rc-secret-export · exec-policy · stale-cli.
+ *              never-synced · stale · repo-behind · repo-drift · version-skew ·
+ *              fleet-resource-gap · orphan · duplicate-hook ·
+ *              duplicate-hook-drift · host-cli-missing · host-cli-invalid ·
+ *              rc-secret-export · exec-policy · stale-cli.
+ *   (RUSH-2162 moved never-synced and duplicate-hook-drift to WARNING: both are
+ *   stale-sync states one `agents sync` resolves, not "needs you now".)
  *
  * This module is pure: it maps already-collected signals (drift rows, orphan
  * rows, repo-behind markers, per-version resource diffs, cross-device divergence,
@@ -70,31 +71,71 @@ function loginShape(agent) {
 }
 /** A machine-stable class for a finding — drives {@link remediationFor} and lets
  *  the JSON consumer group by kind. */
+/** Every finding class. Severity is NOT annotated here — {@link FINDING_SEVERITY}
+ *  below owns it, and a second copy in these comments is a fourth place to drift. */
 export const ALL_FINDING_KINDS = [
-    'logged-out', // provable per-version logout (CRITICAL)
-    'logout-unprovable', // credential absent but not provable (WARNING)
-    'missing-hook', // a declared hook absent from a version home (CRITICAL)
-    'missing-plugin', // a declared plugin absent from a version home (CRITICAL)
-    'unwired-hook', // hook present on disk but not wired into settings.json (CRITICAL)
-    'cli-missing', // a managed agent whose binary won't resolve (CRITICAL)
-    'missing-resource', // a missing command/skill/rule/mcp/permission/subagent (WARNING)
-    'content-drift', // a resource diverged from source (WARNING)
-    'never-synced', // installed but never synced — CRITICAL when its declared
-    // resources are therefore absent, WARNING when it declares none
-    'stale', // sources changed since last sync (WARNING)
-    'repo-behind', // a config repo behind origin (WARNING)
-    'repo-drift', // a config repo diverged from the fleet baseline (WARNING)
-    'fleet-resource-gap', // a resource in another box's central repos, absent here (WARNING)
-    'host-cli-missing', // a declared host CLI not installed on this box (WARNING)
-    'host-cli-invalid', // a host-CLI manifest that failed to parse (WARNING)
-    'version-skew', // an agent version present elsewhere, absent here (WARNING)
-    'orphan', // orphan resources in a version home (WARNING)
-    'duplicate-hook', // one hook materialized in several version homes, byte-identical (WARNING)
-    'duplicate-hook-drift', // …with differing content, so a stale copy can disagree (CRITICAL)
-    'rc-secret-export', // credential-shaped export in a shell rc file (WARNING)
-    'exec-policy', // Windows execution policy blocks agents.ps1 (WARNING)
+    'logged-out', // provable per-version logout
+    'logout-unprovable', // credential absent but not provable
+    'missing-hook', // a declared hook absent from a version home
+    'missing-plugin', // a declared plugin absent from a version home
+    'unwired-hook', // hook present on disk but not wired into settings.json
+    'cli-missing', // a managed agent whose binary won't resolve
+    'missing-resource', // a missing command/skill/rule/mcp/permission/subagent
+    'content-drift', // a resource diverged from source
+    'never-synced', // installed but never synced
+    'stale', // sources changed since last sync
+    'repo-behind', // a config repo behind origin
+    'repo-drift', // a config repo diverged from the fleet baseline
+    'fleet-resource-gap', // a resource in another box's central repos, absent here
+    'host-cli-missing', // a declared host CLI not installed on this box
+    'host-cli-invalid', // a host-CLI manifest that failed to parse
+    'version-skew', // an agent version present elsewhere, absent here
+    'orphan', // orphan resources in a version home
+    'duplicate-hook', // one hook materialized in several version homes, byte-identical
+    'duplicate-hook-drift', // …with differing content, so a stale copy can disagree
+    'rc-secret-export', // credential-shaped export in a shell rc file
+    'exec-policy', // Windows execution policy blocks agents.ps1
     'stale-cli',
 ];
+/**
+ * The severity each kind is emitted with - the SINGLE source of truth, read by
+ * the builders below and asserted against both prose rubrics by
+ * `doctor-findings.test.ts`.
+ *
+ * It exists because severity drifted: the rubrics claimed `never-synced` and
+ * `duplicate-hook-drift` were critical for three days after RUSH-2162 downgraded
+ * them, and the exhaustiveness test missed it because it only checked that a kind
+ * was *named* in the rubric, not which bucket it sat in. Change a severity HERE
+ * and the test names the docs that must move with it.
+ */
+export const FINDING_SEVERITY = {
+    // Needs you now: the harness cannot do its job until this is fixed.
+    'logged-out': 'critical',
+    'missing-hook': 'critical',
+    'missing-plugin': 'critical',
+    'unwired-hook': 'critical',
+    'cli-missing': 'critical',
+    // Everything else is resolvable by a routine sync/cleanup and does not block
+    // the harness right now. RUSH-2162 moved never-synced and duplicate-hook-drift
+    // here: both are stale-sync states that one `agents sync` resolves.
+    'logout-unprovable': 'warning',
+    'missing-resource': 'warning',
+    'content-drift': 'warning',
+    'never-synced': 'warning',
+    'stale': 'warning',
+    'repo-behind': 'warning',
+    'repo-drift': 'warning',
+    'fleet-resource-gap': 'warning',
+    'version-skew': 'warning',
+    'orphan': 'warning',
+    'duplicate-hook': 'warning',
+    'duplicate-hook-drift': 'warning',
+    'host-cli-missing': 'warning',
+    'host-cli-invalid': 'warning',
+    'rc-secret-export': 'warning',
+    'exec-policy': 'warning',
+    'stale-cli': 'warning',
+};
 function agentName(agent) {
     return AGENT_NAMES[agent] || agent;
 }
@@ -241,7 +282,7 @@ export function buildLocalFindings(input) {
     // cli-missing (managed agent, binary broken) — critical.
     for (const agent of input.cliMissing ?? []) {
         out.push(finding({
-            severity: 'critical', kind: 'cli-missing', device, agent,
+            severity: FINDING_SEVERITY['cli-missing'], kind: 'cli-missing', device, agent,
             message: `${agentName(agent)} binary not found`,
         }));
     }
@@ -254,20 +295,20 @@ export function buildLocalFindings(input) {
         if (w?.supported) {
             if (w.settingsMissing) {
                 out.push(finding({
-                    severity: 'critical', kind: 'unwired-hook', device, agent, version,
+                    severity: FINDING_SEVERITY['unwired-hook'], kind: 'unwired-hook', device, agent, version,
                     message: `settings.json missing — ${w.expected ?? 0} declared hook${(w.expected ?? 0) === 1 ? '' : 's'} never fire`,
                 }));
             }
             else if (w.settingsUnparseable) {
                 out.push(finding({
-                    severity: 'critical', kind: 'unwired-hook', device, agent, version,
+                    severity: FINDING_SEVERITY['unwired-hook'], kind: 'unwired-hook', device, agent, version,
                     message: `settings.json unparseable — hook wiring can't be verified`,
                 }));
             }
             else {
                 for (const u of w.unwired) {
                     out.push(finding({
-                        severity: 'critical', kind: 'unwired-hook', device, agent, version,
+                        severity: FINDING_SEVERITY['unwired-hook'], kind: 'unwired-hook', device, agent, version,
                         message: `hook '${u.name}' present on disk but not wired into settings.json`,
                     }));
                 }
@@ -317,17 +358,17 @@ export function buildLocalFindings(input) {
                     missingPlugins.length ? `${missingPlugins.length} plugin${missingPlugins.length === 1 ? '' : 's'}` : '',
                 ].filter(Boolean).join(', ');
                 out.push(finding({
-                    severity: 'warning', kind: 'never-synced', device, agent, version,
+                    severity: FINDING_SEVERITY['never-synced'], kind: 'never-synced', device, agent, version,
                     message: `never synced — ${total} resource${total === 1 ? '' : 's'}${breakdown ? ` (incl. ${breakdown})` : ''} not installed`,
                 }));
             }
         }
         else {
             // Synced-but-drifted: one line per kind of gap on this version.
-            emitGroup(out, missingHooks, 'critical', 'missing-hook', device, agent, version, 'hook', 'missing');
-            emitGroup(out, missingPlugins, 'critical', 'missing-plugin', device, agent, version, 'plugin', 'missing');
-            emitGroup(out, missingOther, 'warning', 'missing-resource', device, agent, version, 'resource', 'missing');
-            emitGroup(out, drifted, 'warning', 'content-drift', device, agent, version, 'resource', 'drifted');
+            emitGroup(out, missingHooks, FINDING_SEVERITY['missing-hook'], 'missing-hook', device, agent, version, 'hook', 'missing');
+            emitGroup(out, missingPlugins, FINDING_SEVERITY['missing-plugin'], 'missing-plugin', device, agent, version, 'plugin', 'missing');
+            emitGroup(out, missingOther, FINDING_SEVERITY['missing-resource'], 'missing-resource', device, agent, version, 'resource', 'missing');
+            emitGroup(out, drifted, FINDING_SEVERITY['content-drift'], 'content-drift', device, agent, version, 'resource', 'drifted');
             if (missingHooks.length + missingPlugins.length + missingOther.length + drifted.length > 0) {
                 detailedVersions.add(`${agent}@${version}`);
             }
@@ -343,7 +384,7 @@ export function buildLocalFindings(input) {
             if (detailedVersions.has(`${row.agent}@${row.version}`))
                 continue;
             out.push(finding({
-                severity: 'warning', kind: 'stale', device, agent: row.agent, version: row.version,
+                severity: FINDING_SEVERITY['stale'], kind: 'stale', device, agent: row.agent, version: row.version,
                 message: 'sources changed since last sync',
             }));
         }
@@ -355,7 +396,7 @@ export function buildLocalFindings(input) {
                 Object.values(rep.kinds).some((rows) => rows.some((r) => r.status === 'missing')));
             if (!hadCritical) {
                 out.push(finding({
-                    severity: 'warning', kind: 'never-synced', device, agent: row.agent, version: row.version,
+                    severity: FINDING_SEVERITY['never-synced'], kind: 'never-synced', device, agent: row.agent, version: row.version,
                     message: 'installed but never synced',
                 }));
             }
@@ -369,7 +410,7 @@ export function buildLocalFindings(input) {
         const stales = input.syncRows.filter((r) => r.status === 'stale').length;
         const staleNote = stales > 0 ? ` → stales ${stales} version${stales === 1 ? '' : 's'}` : '';
         out.push(finding({
-            severity: 'warning', kind: 'repo-behind', device, version: m.alias,
+            severity: FINDING_SEVERITY['repo-behind'], kind: 'repo-behind', device, version: m.alias,
             message: `${m.behind} behind ${m.branch}${staleNote}`,
         }));
     }
@@ -383,7 +424,7 @@ export function buildLocalFindings(input) {
     const missingClis = (input.hostClis?.statuses ?? []).filter((c) => !c.installed).map((c) => c.name);
     if (missingClis.length > 0) {
         out.push({
-            severity: 'warning', kind: 'host-cli-missing', device,
+            severity: FINDING_SEVERITY['host-cli-missing'], kind: 'host-cli-missing', device,
             message: missingClis.length === 1
                 ? `host CLI '${missingClis[0]}' declared but not installed`
                 : `${missingClis.length} declared host CLIs not installed (${missingClis.slice(0, 2).join(', ')}${missingClis.length > 2 ? ', …' : ''})`,
@@ -399,7 +440,7 @@ export function buildLocalFindings(input) {
     // row per bad file, since each needs its own edit.
     for (const e of input.hostClis?.errors ?? []) {
         out.push(finding({
-            severity: 'warning', kind: 'host-cli-invalid', device,
+            severity: FINDING_SEVERITY['host-cli-invalid'], kind: 'host-cli-invalid', device,
             message: `host-CLI manifest ${e.file} could not be read: ${e.reason}`,
         }));
     }
@@ -432,7 +473,7 @@ function orphanFinding(device, rows) {
         ? `${affected[0].agent}@${affected[0].version}`
         : `${affected.length} versions`;
     return [finding({
-            severity: 'warning', kind: 'orphan', device,
+            severity: FINDING_SEVERITY['orphan'], kind: 'orphan', device,
             message: `${total} orphaned resource${total === 1 ? '' : 's'} on ${where} (cleanup only)`,
         })];
 }
@@ -472,7 +513,7 @@ function duplicateHookFindings(device, dups) {
             // stale/sync drift, not a missing hook. Resolvable by one sync; a WARNING,
             // not a "needs you now" critical. (A genuinely MISSING hook stays critical
             // via the missing-hook path.)
-            severity: 'warning',
+            severity: FINDING_SEVERITY[drift ? 'duplicate-hook-drift' : 'duplicate-hook'],
             kind: drift ? 'duplicate-hook-drift' : 'duplicate-hook',
             device, agent, versions, message,
             remediation: `agents sync ${agent}@all --yes`,
@@ -516,7 +557,7 @@ function rcSecretFindings(device, rc) {
                 ? 'agents secrets add, then delete the rc line'
                 : `agents secrets add once per export (${n}), then delete each rc line`;
         out.push({
-            severity: 'warning', kind: 'rc-secret-export', device,
+            severity: FINDING_SEVERITY['rc-secret-export'], kind: 'rc-secret-export', device,
             message: `${what} (${examples}) — readable by any same-user process`,
             remediation,
         });
@@ -537,7 +578,7 @@ function execPolicyFinding(device, execPolicy) {
     if (!blocksLocalScripts(execPolicy.policy))
         return null;
     return finding({
-        severity: 'warning', kind: 'exec-policy', device,
+        severity: FINDING_SEVERITY['exec-policy'], kind: 'exec-policy', device,
         message: `PowerShell execution policy is ${execPolicy.policy} — it blocks the generated agents.ps1 launcher (agents.cmd still works)`,
     });
 }
@@ -630,14 +671,14 @@ export function signInToFindings(device, signIn) {
                 continue;
             if (row.provable) {
                 out.push(finding({
-                    severity: 'critical', kind: 'logged-out', device, agent, version: row.version,
+                    severity: FINDING_SEVERITY['logged-out'], kind: 'logged-out', device, agent, version: row.version,
                     account: row.account ?? null,
                     message: 'logged out — no account signed in',
                 }));
             }
             else {
                 out.push(finding({
-                    severity: 'warning', kind: 'logout-unprovable', device, agent, version: row.version,
+                    severity: FINDING_SEVERITY['logout-unprovable'], kind: 'logout-unprovable', device, agent, version: row.version,
                     account: row.account ?? null,
                     message: 'could not verify sign-in',
                 }));
@@ -662,14 +703,14 @@ export function fleetDivergenceToFindings(divergences, baseline) {
             case 'agent-version-missing-remote':
             case 'agent-version-missing-local':
                 out.push(finding({
-                    severity: 'warning', kind: 'version-skew', device: laggingDevice,
+                    severity: FINDING_SEVERITY['version-skew'], kind: 'version-skew', device: laggingDevice,
                     agent: d.category, version: d.name,
                     message: 'not installed (present elsewhere in the fleet)',
                 }));
                 break;
             case 'repo-drift':
                 out.push(finding({
-                    severity: 'warning', kind: 'repo-drift', device: laggingDevice,
+                    severity: FINDING_SEVERITY['repo-drift'], kind: 'repo-drift', device: laggingDevice,
                     // `category` is the repo ('agents' | 'system'); carry it as the alias
                     // `agents repo pull` expects — ~/.agents is the `user` repo.
                     version: d.category === 'system' ? 'system' : 'user',
@@ -679,7 +720,7 @@ export function fleetDivergenceToFindings(divergences, baseline) {
             case 'resource-missing-remote':
             case 'resource-missing-local':
                 out.push(finding({
-                    severity: 'warning', kind: 'fleet-resource-gap', device: laggingDevice,
+                    severity: FINDING_SEVERITY['fleet-resource-gap'], kind: 'fleet-resource-gap', device: laggingDevice,
                     message: `${d.category.replace(/s$/, '')} '${d.name}' missing (present elsewhere)`,
                 }));
                 break;

package/dist/lib/exec.d.ts

@@ -254,10 +254,14 @@ export interface AgentCommandTemplate {
      *   { subcommand } — replace the headless base subcommand with `<subcommand> <id>`
      *                    (codex: `codex exec` -> `codex exec resume <id>`)
      */
-    resume?: {
+    resume?: ({
         flag: string;
+        interactiveFlag?: string;
+        headlessFlag?: string;
     } | {
         subcommand: string;
+    }) & {
+        since?: string;
     };
 }
 /**
@@ -272,7 +276,7 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
  * command template's `resume` field — the single source of truth. Agents that
  * return false resume via the universal Tier-2 `/continue` replay instead.
  */
-export declare function nativeResume(agent: AgentId): boolean;
+export declare function nativeResume(agent: AgentId, version?: string): boolean;
 /**
  * Build the `-c` value that adds `dir` to codex's workspace-write writable
  * roots. Codex parses the value as TOML, so it's a single-element TOML array of

package/dist/lib/exec.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import { ALL_MODES } from './types.js';
 import { AGENTS } from './agents.js';
 import { parseTimeout } from './routines.js';
-import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
+import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { isTierToken, resolveTier } from './model-tiers.js';
 import { createTimer, redactPrompt, redactArgs } from './events.js';
@@ -385,6 +385,12 @@ export function buildExecEnv(options) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
+    // Durable SessionStart metadata. The hook joins these launch facts to the
+    // harness-provided real session id and writes them under the shared history
+    // directory, so a later resume can restore the permission boundary without
+    // re-parsing harness-specific transcripts.
+    result.AGENTS_RUN_MODE = resolveHeadlessMode(options.agent, normalizeMode(options.mode), resolveInteractive(options), options.modeWarningContext, options.modeWarningState);
+    result.AGENTS_HISTORY_DIR = getHistoryDir();
     // So activity / feed posts stamp the right harness without re-detecting.
     if (options.agent) {
         result.AGENTS_AGENT_NAME = options.agent;
@@ -466,6 +472,7 @@ export const AGENT_COMMANDS = {
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
+        resume: { flag: '--resume', since: '2026.7.23' },
     },
     opencode: {
         base: ['opencode', 'run'],
@@ -589,6 +596,7 @@ export const AGENT_COMMANDS = {
         },
         jsonFlags: ['--output-format', 'streaming-json'],
         modelFlag: '--model',
+        resume: { flag: '--resume', since: '0.2.91' },
     },
     kimi: {
         base: ['kimi'],
@@ -601,6 +609,7 @@ export const AGENT_COMMANDS = {
         },
         jsonFlags: ['--output-format', 'stream-json'],
         modelFlag: '--model',
+        resume: { flag: '--session', since: '0.19.2' },
     },
     // Factory AI Droid (`droid exec` for headless, `droid` for TUI). Flags from
     // docs.factory.ai CLI reference: prompt is positional; --auto low|medium|high
@@ -618,6 +627,7 @@ export const AGENT_COMMANDS = {
         },
         jsonFlags: ['-o', 'stream-json'],
         modelFlag: '-m',
+        resume: { flag: '--resume', headlessFlag: '--session-id', since: '0.186.0' },
     },
     hermes: {
         base: ['hermes', 'chat'],
@@ -633,8 +643,13 @@ export const AGENT_COMMANDS = {
  * command template's `resume` field — the single source of truth. Agents that
  * return false resume via the universal Tier-2 `/continue` replay instead.
  */
-export function nativeResume(agent) {
-    return AGENT_COMMANDS[agent]?.resume !== undefined;
+export function nativeResume(agent, version) {
+    const resume = AGENT_COMMANDS[agent]?.resume;
+    if (!resume)
+        return false;
+    if (!resume.since)
+        return true;
+    return !!version && compareVersions(version, resume.since) >= 0;
 }
 /**
  * Build the `-c` value that adds `dir` to codex's workspace-write writable
@@ -822,7 +837,10 @@ export function buildExecCommand(options) {
     // `resume`, the legacy claude-only `--session-id` CREATES a session with that id.
     if (options.resume && options.sessionId && resumeSpec) {
         if ('flag' in resumeSpec) {
-            cmd.push(resumeSpec.flag, options.sessionId);
+            const flag = interactive
+                ? (resumeSpec.interactiveFlag ?? resumeSpec.flag)
+                : (resumeSpec.headlessFlag ?? resumeSpec.flag);
+            cmd.push(flag, options.sessionId);
         }
         else {
             cmd.push(options.sessionId);

package/dist/lib/hooks.d.ts

@@ -58,8 +58,10 @@ export interface DuplicateVersionHook {
 export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
 /**
  * List hook entries in a single directory, grouping script + data files by
- * basename. Exported so doctor-diff can reuse the same grouping the sync path
- * applies; without this, doctor would double-count `foo.sh` and `foo.yaml`.
+ * basename. Also discovers scripts in one-level group subdirs
+ * (hooks/session-starts/). Exported so doctor-diff can reuse the same grouping
+ * the sync path applies; without this, doctor would double-count `foo.sh` and
+ * `foo.yaml`. On basename collision, the top-level file wins over a nested one.
  */
 export declare function listHookEntriesFromDir(dir: string): HookEntry[];
 /**